Hi Bruno,

Are you using the SSL certificate to convey claims like email etc.? As I 
understand SSL it will be imposible to cache anything like you normaly can 
using REST - is that right? Seems like you loose something that way - 
especially if it's not encryption you are aiming for, but only trust in 
claims.

> This being said, discovering the identity in FOAF+SSL is really where
> this system makes use of REST: your ID is a URI (a WebID) than can be
> dereferenced and about which things can be said using RDF/semantic web.

Yes, using a URL as an ID seems like a good idea. As you say, you can state 
all sorts of thing at the end of the URL. As I remember it, this is quite a 
bit like what OpenID is doing, and, using some crypto stuff I do not 
understand, the server can be assured that the URL is in fact controlled by 
the client.

> I sometimes wish there were 'WWW-Authenticate: transport' (or something
> similar, to make handling tokens out of HTTP like SSL client-certificate
> cleaner, and thus avoid some problems related to the TLS renegotiation
> issue) or 'WWW-Authenticate: token' (to have clear
> authentication-dedicated tokens, rather than cookies that are also used
> for sessions), but they just don't exist in browser.

Okay, so using SSL, OpenID, SAML, whatever: it seems like their is no 
standard way of transporting non-username/passsword claims after an initial 
handshake, except for using cookies.

So the defacto standard way is quite simple: use cookies for storing 
proprietary security claims or session identifiers. Right?

Or, if you ignore browsers, you can use "Authorization: MyVendorAuth XYZ" 
where MyVendorAuth identifies a proprietary claims-encoding method. Right?

/J�rn

----- Original Message ----- 
From: "Bruno Harbulot" <Bruno.Harbulot@...>
To: <rest-discuss@yahoogroups.com>
Sent: Wednesday, December 30, 2009 6:12 PM
Subject: [rest-discuss] Re: RESTful claims-based authorization


> Hello J�rn,
>
> You could in principle define your own headers (or try to standardise
> some headers) to propagate SAML assertions (or similar tokens) in a
> RESTful way. Unfortunately, that's unlikely to work in browsers.
>
> Even SAML's HTTP Redirect (GET) Binding is often only a one-off thing
> that can only be used to log in (and thus get a cookie), otherwise you'd
> have to repeat this query for all URIs you want to use (and thus change
> the URI, since the query is part of the URI, strictly speaking).
>
> We've been doing some work on FOAF+SSL whereby you avoid the non-RESTful
> authentication issue by using a TLS/SSL client-certificate for the
> authentication (which is under the HTTP level), but for servers that
> don't support SSL (or even the settings required for FOAF+SSL), we've
> also had to use some SSO-like login mechanism via cookies.
> This being said, discovering the identity in FOAF+SSL is really where
> this system makes use of REST: your ID is a URI (a WebID) than can be
> dereferenced and about which things can be said using RDF/semantic web.
>
>
> The issue of using cookies for authentication/authorisation comes from
> the lack of browser support (and standardisation) for other headers.
> I sometimes wish there were 'WWW-Authenticate: transport' (or something
> similar, to make handling tokens out of HTTP like SSL client-certificate
> cleaner, and thus avoid some problems related to the TLS renegotiation
> issue) or 'WWW-Authenticate: token' (to have clear
> authentication-dedicated tokens, rather than cookies that are also used
> for sessions), but they just don't exist in browser.
> Would it be worth suggesting this approach to the HTTP WG? Perhaps, but
> there's little point doing so if the major browser vendors are not on
> board. I presume most people consider that cookies are an acceptable
> practical solution, even if it breaks the REST principles.
>
>
> Best wishes,
>
> Bruno.
>
>
> J�rn Wildt wrote:
>>
>>
>> Is there any standard RESTful way of doing claims based authorization 
>> a'la
>> SAML and CardSpace? The authorization schemes I have seen so far usually
>> encodes a user reference and nothing more - there's no secure way to 
>> assert
>> claims like email=xxx@... <mailto:email%3Dxxx%40yyy.zz> or
>> employeenumber=12345 or age-below-twenty.
>>
>> I guess you can use SAML "HTTP Redirect (GET) Binding", but that 
>> generates
>> such a huge URL that it seems impractical to use (it's a base-64
>> encoding of
>> a zip-encoding of a SAML XML document).
>>
>> As I understand it a RESTful authorization scheme must be stateless, so 
>> you
>> cannot rely on any kind of session use. This means you have to transfer 
>> all
>> the claims on each and every request which again means a potentially big
>> overhead.
>>
>> What is needed is a standard way of encoding multiple claims in a 
>> compact,
>> secure, trusted way such that they can be transferred on each request
>> without too much overhead (including whatever crypto stuff is needed).
>>
>> Maybe you could create a temporary ressource somewhere with the claims,
>> then
>> at least you only had to transfer the claims URL, not all the claims, and
>> the server could then cache these claims.
>>
>> Any ideas or references?
>>
>> It even occurs to me that claims could be more RESTful than
>> username/password since they don't require any out-of-band setup of user
>> accounts. All that is needed is a standard for claims and then everything
>> should work if the claims are issued by an authority that the web service
>> trusts. No need for any human interaction - the server just sends a
>> challenge "show me your claims (and I accept them from authority X, Y and
>> Z)" whereafter the client sends the claims. These claims can even be
>> obtained without human interaction if the client and the claims server
>> trust
>> each other.
>>
>> Comments?
>>
>> Thanks, J�rn
>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

As this thread seems to have come to a stop, I'll reference the  
conclusion I reached over at the atom-protocol list for those that do  
not follow both lists. It pretty much answers the question for me.

See http://www.imc.org/atom-protocol/mail-archive/msg11490.html

Jan



On Dec 16, 2009, at 4:21 PM, Jan Algermissen wrote:

> I can't help it: I see no possible way to implement a non-human-driven
> client for a service without (in one way or another) classifying the
> resources the service provides.
>
> For example, consider a helpdesk ticket system: When writing a client
> that searches for tickets and then updates the foo:status of the
> individual tickets contained in the result set, I need to make the
> assumption that the result set contains tickets (and not just
> resources). In order to being able to make such an assumptions, the
> classification information must be made available by the service. In
> addition, when client developers should be enabled to develop clients
> before the services exist this information is needed as some form of
> service type description. The specification of application/atomsrv+xml
> is a good example of such a service type description.
>
> But however this is approached, it essentially comes down to telling
> the client what kinds of resources (IOW: kinds of application states)
> to expect on the server. I just cannot code to update the resource
> foo:status when I have now clue that this user goal is applicable to
> the resource in the first place.
>
> Does anyone have an idea how to align this (IMHO fact) with the
> constraint that no information about resource types must be made
> available to clients in RESTful systems?
>
> Jan
>
> P.S. In human driven interactions the situation is different: We still
> have knowledge of the resource type iin general (we know a trouble
> ticket when we see one) but we are not dependent on knowing that the
> result of some interaction will be a trouble ticket. We can allways
> follow some human-targeted links and make a few hops to reach the
> trouble ticket resource we expect should be 'somwehere'. M2M clients
> do not have that luxury (unless we apply some form of AI I guess).
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

I've posted "DOCTR: a better approach to HTTP transactions" to my blog
(http://amundsen.com/blog/archives/1024) and welcome any feedback.

Some excerpts:

<snip>
A better approach is to expose an HTTP-compliant transaction service
interface (TSI) that takes advantage of the protocol's inherent
architectural style. Transactions over HTTP should be optional,
discoverable, negotiable, based on optimistic commits, and (in the
case of failures) use compenstating requests as a way to reverse
previous work.
</snip>

and

<snip>
What is described here is a transaction service interface (TSI) that
clients and servers can choose to implement in ways all parties can
agree upon. This is the way media-types are currenly handled and TSIs
could be defined, documented, and registered in much the same way.
This includes the possibility of registering a media-type that matches
the TSI implementation. True to the archetictural style of the HTTP
protocol, this approach proposes a "uniform interface" for handling
units of work over HTTP.
</snip>

Thanks in advance.

mca
http://amundsen.com/blog/

Watching this was well worth my time:

http://www.infoq.com/presentations/Systems-that-Never-Stop-Joe-Armstrong

I'm integrating Joe's ideas (and those of his source references) into my
applied REST architecture work. I don't think in terms of coding,
particularly in Erlang.  But, some of Joe's laws have direct
corollaries in REST -- the layered system and self-descriptive
messaging constraints come to mind.  Others have direct corollaries in
my proposed system architecture, like using ZFS for storage, and Solaris
Zones to isolate system layers executing on the same computer.

REST allows for a system which obeys Joe's laws for system reliability.
While it specifies the layered system constraint, REST says nothing
about isolating those layers for concurrency.  To meet the "software
development on the scale of decades" goal of REST, I believe applied
REST architecture should extend beyond REST per se, and consider other
requirements of a long-running system like isolation and concurrency.

Joe's Stable Storage law is highly pragmatic to the goals of a REST
system, even though REST itself says nothing of storage.  Isn't the
notion of persistent storage something that belongs in an architectural
model of an overall system?  There are certainly plenty of alternatives
for implementation.  Just because it isn't part of REST seems no reason
to exclude all notion of storage from the Model.  Having a "law" to
follow for the long-term development of a storage system, or achieve
isolation and concurrency of layers, serves exactly the same purpose as
having a "law" to follow (REST) for messaging between connectors.

Isolation and concurrency are addressed by layered system and Zones.
Self-descriptive messaging directly addresses what Joe's saying about
failure detection and fault identification -- restricting communication
to a uniform REST interface eases error detection and debugging.  As to
error correction, I agree with fail-early-and-exit, just like a browser
does when the application/xhtml+xml media type is used, but has ill-
formed XSLT output.  Other media types cause browsers to handle XSLT
output as text/html, meaning an error resulting from a syntax error in
the HTML output may escape notice for an unacceptable length of time
(i.e., until something that should have been caught during development
winds up being filed as a bug report).

Live Code Upgrade is important to REST also.  Joe's clearly talking
about something else entirely, however REST's layered system constraint
makes it possible to swap out components in a system without affecting
users, provided that messaging is stateless.  What Joe's saying about
stateless messaging's importance in OOP/COP directly applies to REST.
REST also allows client-side code to be changed at any time, due to the
hypertext constraint.  Changes to a REST system are easy to roll out
and roll back.  Joe makes an important point that may be restated as,
altering your server-side code ought to be possible without rebooting
the computer (or even a Zone within a computer), as this affects other
running processes.

A REST "system that never stops" is a goal which may be achieved
independently of language choice, although I am in favor of functional
programming.  In fact, I see this as a key reason to use XSLT over
Javascript whenever possible -- immutable data as the basis for
browser-resident code is less likely to crash some random system.

My point is, the REST architectural style doesn't address key aspects of
system architecture, like storage.  So how can REST alone be the basis
for any applied-software-architecture Implementation?  The Model should
therefore address issues like isolation, concurrency and storage based
on the REST-agnostic laws of long-running systems.  These laws clearly
apply to the goals of any system that needs REST in the first place.

-Eric

On Tue, Jan 5, 2010 at 9:21 PM, mike amundsen <mamund@...> wrote:
> <snip>
> A better approach is to expose an HTTP-compliant transaction service
> interface (TSI) that takes advantage of the protocol's inherent
> architectural style. Transactions over HTTP should be optional,
> discoverable, negotiable, based on optimistic commits, and (in the
> case of failures) use compenstating requests as a way to reverse
> previous work.
> </snip>

Compensation often does not work.  Think of an offer to buy.  If it's
optimistically committed, both buyer and seller may take followup
actions that could be difficult or impossible to undo (e.g. starting
production) if the offer is cancelled.  Alternatively, both parties
may need to wait for some undeterminate timespan to make sure a
compensating request does not arrive.

A better alternative in many situations, which I've described on this
list before, is to use a provisional-final pattern, where the initial
request is provisional, and then both parties agree that it should be
made final or cancelled.  All these interactions can be done
RESTfully.

An example in regular business practice is a request for quotation
(provisional) followed by an order (final).

You may think that is not a transaction, but it follows a 2-phase
commit pattern, altho it does not obey all the ACID rules (which are
impossible to follow RESTfully).

On Jan 6, 2010, at 10:24 AM, Eric J. Bowman wrote:

> My point is, the REST architectural style doesn't address key  
> aspects of
> system architecture, like storage.  So how can REST alone be the basis
> for any applied-software-architecture Implementation?  The Model  
> should
> therefore address issues like isolation, concurrency and storage based
> on the REST-agnostic laws of long-running systems.  These laws clearly
> apply to the goals of any system that needs REST in the first place.


RESTs primary goal is not fault tolerance but decentralized evolution,  
scalability and simplicity. REST's focus is coordination of components  
owned by independent parties. I think the comparision you try to make  
is a bit problematic.

However, there is certainly a lot of overlap between the area of  
application. The stateless server constraint for example enables live  
server upgrade and the hypermedia constraint even enables changing the  
server side state machine while the client is stepping through it from  
hyperlink to hyperlink.

In fact I find it hard to see how you could achieve better fault  
tolerance regarding the component communication than the fault  
tolerance you have with TCP/IP, DNS and HTTP.

Jan


--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

> An example in regular business practice is a request for quotation
(provisional) followed by an order (final).
> You may think that is not a transaction, but it follows a 2-phase
commit pattern, altho it does not obey all the ACID rules (which are
impossible to follow RESTfully).

I agree. My only doubt so far is that in this case the client should be fat
enough to know how to deal with situations where it breaks between the first
and second step working with two resources.

i.e. the user wants to buy a set of products, which was broken by the client
app in two subsets, each one to be bought in two different suppliers. Both
request for quotations were sent successfully, one order is also fine, but
the second order breaks due to out-of-stock issues (someone just bought
it.... not acid). The client is now responsible for trying to cancel that
first order.

Any workarounds/suggestions?


Guilherme Silveira
Caelum | Ensino e Inova��o
http://www.caelum.com.br/


On Wed, Jan 6, 2010 at 10:45 AM, Bob Haugen <bob.haugen@...> wrote:

>
>
> On Tue, Jan 5, 2010 at 9:21 PM, mike amundsen <mamund@...<mamund%40yahoo.com>>
> wrote:
> > <snip>
> > A better approach is to expose an HTTP-compliant transaction service
> > interface (TSI) that takes advantage of the protocol's inherent
> > architectural style. Transactions over HTTP should be optional,
> > discoverable, negotiable, based on optimistic commits, and (in the
> > case of failures) use compenstating requests as a way to reverse
> > previous work.
> > </snip>
>
> Compensation often does not work. Think of an offer to buy. If it's
> optimistically committed, both buyer and seller may take followup
> actions that could be difficult or impossible to undo (e.g. starting
> production) if the offer is cancelled. Alternatively, both parties
> may need to wait for some undeterminate timespan to make sure a
> compensating request does not arrive.
>
> A better alternative in many situations, which I've described on this
> list before, is to use a provisional-final pattern, where the initial
> request is provisional, and then both parties agree that it should be
> made final or cancelled. All these interactions can be done
> RESTfully.
>
> An example in regular business practice is a request for quotation
> (provisional) followed by an order (final).
>
> You may think that is not a transaction, but it follows a 2-phase
> commit pattern, altho it does not obey all the ACID rules (which are
> impossible to follow RESTfully).
>
>  
>

On Jan 6, 2010, at 2:00 PM, Guilherme Silveira wrote:

>
>
> > An example in regular business practice is a request for quotation
> (provisional) followed by an order (final).
> > You may think that is not a transaction, but it follows a 2-phase
> commit pattern, altho it does not obey all the ACID rules (which are
> impossible to follow RESTfully).
>
> I agree. My only doubt so far is that in this case the client should  
> be fat enough to know how to deal with situations where it breaks  
> between the first and second step working with two resources.
>
> i.e. the user wants to buy a set of products, which was broken by  
> the client app in two subsets, each one to be bought in two  
> different suppliers. Both request for quotations were sent  
> successfully, one order is also fine, but the second order breaks  
> due to out-of-stock issues (someone just bought it.... not acid).  
> The client is now responsible for trying to cancel that first order.
>
> Any workarounds/suggestions?

This inevitably leads to 2PC kind of problems and the usually best way  
to deal with that in practice is to simply account for the fact that  
some errors occur. That way, you loose some e.g. customers but gain  
the possibility to create manageable software systems. Flight  
overbooking is the best example.

Jan


>
>
> Guilherme Silveira
> Caelum | Ensino e Inova��o
> http://www.caelum.com.br/
>
>
> On Wed, Jan 6, 2010 at 10:45 AM, Bob Haugen <bob.haugen@...>  
> wrote:
>
>
> On Tue, Jan 5, 2010 at 9:21 PM, mike amundsen <mamund@...>  
> wrote:
> > <snip>
> > A better approach is to expose an HTTP-compliant transaction service
> > interface (TSI) that takes advantage of the protocol's inherent
> > architectural style. Transactions over HTTP should be optional,
> > discoverable, negotiable, based on optimistic commits, and (in the
> > case of failures) use compenstating requests as a way to reverse
> > previous work.
> > </snip>
>
> Compensation often does not work. Think of an offer to buy. If it's
> optimistically committed, both buyer and seller may take followup
> actions that could be difficult or impossible to undo (e.g. starting
> production) if the offer is cancelled. Alternatively, both parties
> may need to wait for some undeterminate timespan to make sure a
> compensating request does not arrive.
>
> A better alternative in many situations, which I've described on this
> list before, is to use a provisional-final pattern, where the initial
> request is provisional, and then both parties agree that it should be
> made final or cancelled. All these interactions can be done
> RESTfully.
>
> An example in regular business practice is a request for quotation
> (provisional) followed by an order (final).
>
> You may think that is not a transaction, but it follows a 2-phase
> commit pattern, altho it does not obey all the ACID rules (which are
> impossible to follow RESTfully).
>
>
>
>
> 

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

On Wed, Jan 6, 2010 at 4:24 AM, Eric J. Bowman <eric@...> wrote:
> Watching this was well worth my time:
>
> http://www.infoq.com/presentations/Systems-that-Never-Stop-Joe-Armstrong
>
> I'm integrating Joe's ideas (and those of his source references) into my
> applied REST architecture work. I don't think in terms of coding,
> particularly in Erlang. �But, some of Joe's laws have direct
> corollaries in REST -- the layered system and self-descriptive
> messaging constraints come to mind. �Others have direct corollaries in
> my proposed system architecture, like using ZFS for storage, and Solaris
> Zones to isolate system layers executing on the same computer.
>
> REST allows for a system which obeys Joe's laws for system reliability.
> While it specifies the layered system constraint, REST says nothing
> about isolating those layers for concurrency. �To meet the "software
> development on the scale of decades" goal of REST, I believe applied
> REST architecture should extend beyond REST per se, and consider other

An "applied REST architecture" extends REST by definition, right?  On
the other hand, if you're talking about starting with REST and
applying additional constraints, that would be creating a new style
hybrid style based on but not REST?

> requirements of a long-running system like isolation and concurrency.

Regarding isolation, a RESTful system gets the same property (e.g.
reliability) evoked by way of being a hybrid of the
client-stateless-server style through separation of concern+stateless
right?

I'm only familiar with concurrency withing application architecture
and his talk is simply trumpeting message-passing over shared-memory -
which is important at that level of abstraction.  It seems to me that
the REST architecture is inherently concurrency friendly, can you
elaborate on what's missing?

> Joe's Stable Storage law is highly pragmatic to the goals of a REST
> system, even though REST itself says nothing of storage. �Isn't the
> notion of persistent storage something that belongs in an architectural
> model of an overall system?

It seems important to origin servers within a system but not relevant
to the REST style itself.  It's not the level of abstraction that REST
was intended to address is it?  I'm not clear on how you're using the
term "architectural *model*" - if it's a model of the REST
architectural style, it seems that discussing storage is out of scope.
 Suppose you wanted to achieve this by adding a new constraint,
wouldn't the constraint at this level of abstraction have to be in
terms of the addressability of the resource over time?

> My point is, the REST architectural style doesn't address key aspects of
> system architecture, like storage. �So how can REST alone be the basis
> for any applied-software-architecture Implementation? �The Model should
> therefore address issues like isolation, concurrency and storage based
> on the REST-agnostic laws of long-running systems.

That seems to run counter to the framework on which REST is based
though.  At this level of architectural abstraction, the focus
shouldn't be on "how do we address isolation" but, rather, how can we
maximally induce isolation.  Similarly, we shouldn't worry about
concurrency, but rather performance and user-perceived performance.
The framework is good because it encourages reasonable decisions in
terms of desired properties instead of the technical mechanism.

--tim

oops...  +4s/isolation/reliability

> That seems to run counter to the framework on which REST is based
> though. �At this level of architectural abstraction, the focus
> shouldn't be on "how do we address isolation" but, rather, how can we
> maximally induce *reliability*. �Similarly, we shouldn't worry about
> concurrency, but rather performance and user-perceived performance.
> The framework is good because it encourages reasonable decisions in
> terms of desired properties instead of the technical mechanism.

On Wed, Jan 6, 2010 at 7:00 AM, Guilherme Silveira
<guilherme.silveira@caelum.com.br> wrote:
> > An example in regular business practice is a request for quotation
> > (provisional) followed by an order (final).
> > You may think that is not a transaction, but it follows a 2-phase
> > commit pattern, altho it does not obey all the ACID rules (which are
> > impossible to follow RESTfully).

> I agree. My only doubt so far is that in this case the client should be fat enough to know how to deal with situations where it breaks between the first and second step working with two resources.
> i.e. the user wants to buy a set of products, which was broken by the client app in two subsets, each one to be bought in two different suppliers. Both request for quotations were sent successfully, one order is also fine, but the second order breaks due to out-of-stock issues (someone just bought it.... not acid). The client is now responsible for trying to cancel that first order.
> Any workarounds/suggestions?

If I understand correctly, you are posing a situation where the
provisional phase (quotations) has become final (orders, which both
buyer and seller have agreed to) and now the second seller has failed
to deliver so the buyer wants to cancel the first order.  Correct?

Ain't no transaction protocol that will save you.  As Jan Algermissen
suggested, stuff happens...

If the orders had penalty clauses, the second seller may need to make
good.  If the first order had a cancellation fee, the buyer may need
to pay it.  And the first seller may lose some resources of some type.

> Ain't no transaction protocol that will save you. As Jan Algermissen
suggested, stuff happens...
That's what I thought, but maybe I was wrong. Thanks Bob, Jan...


> If the orders had penalty clauses, the second seller may need to make
> good. If the first order had a cancellation fee, the buyer may need
> to pay it. And the first seller may lose some resources of some type.
>  
>

Bob:

Thanks for the feedback. I agree that my example does not cover all
possibilities. In fact, I referenced (as  "final commit") the
interaction type you mention here as one that I was not focusing upon
in this first post.

So far, I've treated provisional-final work as application-level
activity. The approach I outlined here attempts to describe a pattern
for handling transaction details when they are _not_ the primary
application activity, but orthogonal to it (if I'm using that word
correctly).

Having said that, I think it is possible to use a "uniform transaction
service interface" approach to handle provisional-final interactions.
In this case, a Content-Trans:provisional-final header could be
advertised by servers and negotiated for by clients. The returned
LINK[rel="trans"] element (in a header or in the representation) could
point to a URI that allows not only a GET (to view the status of the
transaction) and a DELETE (to cancel the open work), but also a POST
to execute the "final." Alternately, the representation returned in
the GET to the transaction URI could contain one or more link elements
needed to progress the unit of work to it's ultimate completion.


mca
http://amundsen.com/blog/




On Wed, Jan 6, 2010 at 07:45, Bob Haugen <bob.haugen@...> wrote:
> On Tue, Jan 5, 2010 at 9:21 PM, mike amundsen <mamund@...> wrote:
>> <snip>
>> A better approach is to expose an HTTP-compliant transaction service
>> interface (TSI) that takes advantage of the protocol's inherent
>> architectural style. Transactions over HTTP should be optional,
>> discoverable, negotiable, based on optimistic commits, and (in the
>> case of failures) use compenstating requests as a way to reverse
>> previous work.
>> </snip>
>
> Compensation often does not work. �Think of an offer to buy. �If it's
> optimistically committed, both buyer and seller may take followup
> actions that could be difficult or impossible to undo (e.g. starting
> production) if the offer is cancelled. �Alternatively, both parties
> may need to wait for some undeterminate timespan to make sure a
> compensating request does not arrive.
>
> A better alternative in many situations, which I've described on this
> list before, is to use a provisional-final pattern, where the initial
> request is provisional, and then both parties agree that it should be
> made final or cancelled. �All these interactions can be done
> RESTfully.
>
> An example in regular business practice is a request for quotation
> (provisional) followed by an order (final).
>
> You may think that is not a transaction, but it follows a 2-phase
> commit pattern, altho it does not obey all the ACID rules (which are
> impossible to follow RESTfully).
>

On Wed, Jan 6, 2010 at 8:24 AM, Bob Haugen <bob.haugen@...> wrote:
> So a 2PC client-server interaction might have classical ACID database
> transactions on the server for each request, but the full client
> experience would have 2 phases at a higher level.

P.S. compensation is also 2PC, just with an optional 2nd phase.

On Wed, Jan 6, 2010 at 8:14 AM, mike amundsen <mamund@...> wrote:
> So far, I've treated provisional-final work as application-level
> activity.

I think once you are doing anything on HTTP it's all application-level.

> I think it's true that 2PC-style transactions over HTTP are not needed.
> Two-Phase Commit may be important on the server-side behind the HTTP interface
> between the client and server, but there is no reason to expose them to HTTP clients;
> they don't care what goes on at the server.

You may be confusing 2PC with ACID.  Peter Furniss once told me that
any application-level agreement requires 2 phases, that is, 2PC in
some form or other.  You just don't get Isolation over HTTP, and you
shouldn't hold locks over a long-running process dependent on a
response from an unreliable partner.

So a 2PC client-server interaction might have classical ACID database
transactions on the server for each request, but the full client
experience would have 2 phases at a higher level.

Bob:

<snip>
I think once you are doing anything on HTTP it's all application-level.
</snip>
I've been focusing on the the control data aspect HTTP lately. It's
used to handle authentication, encoding, caching, etc.  My attempt
here has been to see if there is value in treating some level of
transactions as control data instead of first-class application
information.

</snip>
You may be confusing 2PC with ACID.
</snip>
I think you're correct. Thanks.

mca
http://amundsen.com/blog/




On Wed, Jan 6, 2010 at 09:24, Bob Haugen <bob.haugen@...> wrote:
> On Wed, Jan 6, 2010 at 8:14 AM, mike amundsen <mamund@...> wrote:
>> So far, I've treated provisional-final work as application-level
>> activity.
>
> I think once you are doing anything on HTTP it's all application-level.
>
>> I think it's true that 2PC-style transactions over HTTP are not needed.
>> Two-Phase Commit may be important on the server-side behind the HTTP interface
>> between the client and server, but there is no reason to expose them to HTTP clients;
>> they don't care what goes on at the server.
>
> You may be confusing 2PC with ACID. �Peter Furniss once told me that
> any application-level agreement requires 2 phases, that is, 2PC in
> some form or other. �You just don't get Isolation over HTTP, and you
> shouldn't hold locks over a long-running process dependent on a
> response from an unreliable partner.
>
> So a 2PC client-server interaction might have classical ACID database
> transactions on the server for each request, but the full client
> experience would have 2 phases at a higher level.
>

Jan Algermissen wrote:
> 
> On Jan 6, 2010, at 10:24 AM, Eric J. Bowman wrote:
> 
> > My point is, the REST architectural style doesn't address key  
> > aspects of
> > system architecture, like storage.  So how can REST alone be the
> > basis for any applied-software-architecture Implementation?  The
> > Model should
> > therefore address issues like isolation, concurrency and storage
> > based on the REST-agnostic laws of long-running systems.  These
> > laws clearly apply to the goals of any system that needs REST in
> > the first place.
> 
> 
> RESTs primary goal is not fault tolerance but decentralized
> evolution, scalability and simplicity. REST's focus is coordination
> of components owned by independent parties. I think the comparision
> you try to make is a bit problematic.
> 

I think it depends on what one means by fault-tolerant.  I hate when a
website hangs entirely because some ad rotator isn't responding.  If my
website doesn't hang in such a case, I'd consider it fault-tolerant, as
it's the best I can do when dealing with third-party components.  REST
takes into account the unreliability of the network itself.  If my
website goes offline only in a particular region, I'd consider it fault-
tolerant.  So fault tolerance on REST's global scale, is a different
beast entirely from fault tolerance within a programming language or OS.

But you do make a good argument.

>
> However, there is certainly a lot of overlap between the area of  
> application. The stateless server constraint for example enables
> live server upgrade and the hypermedia constraint even enables
> changing the server side state machine while the client is stepping
> through it from hyperlink to hyperlink.
> 
> In fact I find it hard to see how you could achieve better fault  
> tolerance regarding the component communication than the fault  
> tolerance you have with TCP/IP, DNS and HTTP.
> 

Exactly!  REST gets you most of the way to these laws for high
availability systems.  If you really need Web scale and REST, you
probably want high availability anyway, so I think it may be useful to
incorporate these ideas into an abstract model of a system, where the
purpose of that model is to guide long-term development towards an
ideal that may always lie just over the horizon.

-Eric

Tim Williams wrote:
>
> > REST allows for a system which obeys Joe's laws for system
> > reliability. While it specifies the layered system constraint, REST
> > says nothing about isolating those layers for concurrency. �To meet
> > the "software development on the scale of decades" goal of REST, I
> > believe applied REST architecture should extend beyond REST per se,
> > and consider other
> 
> An "applied REST architecture" extends REST by definition, right?  On
> the other hand, if you're talking about starting with REST and
> applying additional constraints, that would be creating a new style
> hybrid style based on but not REST?
> 

I don't think that applying REST architecture extends REST in any way.
"REST... [focuses] on the roles of components, the constraints upon
their interaction with other components, and their interpretation of
significant data elements."  That's a limited scope within an overall
system.  My choice of storage implementation has nothing to do with the
roles of any components, or the constraints upon messaging between
components, or the interpretation of data.  So I'm not really creating
an additional REST constraint, or altering the REST style in any way.

The idea of applied software architecture is to create mappings from
the abstraction to the implementation.  But the abstraction of an
entire REST system as a model for its developers to follow, needs to
address component implementation, which is outside the scope of REST.
The overall architecture encompasses REST to provide a uniform
interface.  Implementation details are hidden behind this uniform
interface, so from the user perspective the system is only REST --
users care nothing about storage implementation, only HTTP interaction.

-Eric

Compensation is not the same as undo, that is a big error in this discussion.  Undo is a recovery mechanism. Compensation is something every transaction needs to have. Every well formed transaction has a compensating transaction associated with it. The classic example is for a credit card debit transaction, a corresponding credit card credit compensating transaction is defined in case an erroneous charge was made. Compensation has nothing to do with recovery. It's about compensating for an erroneous transaction.

A similar bit of bad logic is involved in the idea of a "provisional" transaction.  I realize this idea has been around for a while, and there are several proponents of it. However a transaction is a transaction, and either it is complete or it is not complete and is rolled back (or undone). If you want to model two transactions, that's fine, but don't call one "provisional" when it has the exact same semantics as the "real" transaction.

The best modeling of a transaction for REST is to model a transaction as a resource, as is described in the "RESTful Web Services" book. Phil and I incorporated that into the second edition of our TP book.  We did not include "provisional" transactions because they don't really accomplish anything.  If you want to have a more "optimistic" approach to transaction modeling, the classic "pseudo conversational" model is the way to go.  

Eric




________________________________
From: Bob Haugen <bob.haugen@...>
To: mike amundsen <mamund@...>
Cc: rest-discuss <rest-discuss@yahoogroups.com>
Sent: Wed, January 6, 2010 7:45:15 AM
Subject: Re: [rest-discuss] A different approach to supporting transactions  over HTTP

  
On Tue, Jan 5, 2010 at 9:21 PM, mike amundsen <mamund@yahoo. com> wrote:
> <snip>
> A better approach is to expose an HTTP-compliant transaction service
> interface (TSI) that takes advantage of the protocol's inherent
> architectural style. Transactions over HTTP should be optional,
> discoverable, negotiable, based on optimistic commits, and (in the
> case of failures) use compenstating requests as a way to reverse
> previous work.
> </snip>

Compensation often does not work.  Think of an offer to buy.  If it's
optimistically committed, both buyer and seller may take followup
actions that could be difficult or impossible to undo (e.g. starting
production) if the offer is cancelled.  Alternatively, both parties
may need to wait for some undeterminate timespan to make sure a
compensating request does not arrive.

A better alternative in many situations, which I've described on this
list before, is to use a provisional- final pattern, where the initial
request is provisional, and then both parties agree that it should be
made final or cancelled.  All these interactions can be done
RESTfully.

An example in regular business practice is a request for quotation
(provisional) followed by an order (final).

You may think that is not a transaction, but it follows a 2-phase
commit pattern, altho it does not obey all the ACID rules (which are
impossible to follow RESTfully).

 


      

I should probably explain that Eric Newcomer is an expert in
transactions and I am not. �Nevertheless, I disagree, and will cite
some other transaction experts (below).

(And I promised to myself I would stop engaging in this thread, but whatever...)

(And yes this level of transactional detail is probably off-topic for
REST-discuss so I will shut up now...)

On Wed, Jan 6, 2010 at 7:49 PM, Eric Newcomer <e_newcomer@...> wrote:
>
> Compensation is not the same as undo, that is a big error in this discussion.

Compensation has been used as undo, as a replacement for cancel or
abort in the 2nd phase of 2PC, in several transactional methods,
including BTP (below) and Sagas:
www.cs.cornell.edu/andru/cs711/2002fa/reading/sagas.pdf

"To amend partial executions, each saga T, should be provided with a
compensating transaction C. The compensating transaction undoes, from
a semantic point of view, any of the actions performed by T, but does
not necessarily return the database to the state that existed when the
execution of T began."

> A similar bit of bad logic is involved in the idea of a "provisional" transaction.� I realize this idea has been around for a while, and there are several proponents of it. However a transaction is a transaction, and either it is complete or it is not complete and is rolled back (or undone). If you want to model two transactions, that's fine, but don't call one "provisional" when it has the exact same semantics as the "real" transaction.
>

That is an inaccurate representatiton of the provisional-final
pattern, leaving off the "final" part (the 2nd phase).

Here's one fairly early version. The paper is introduced by its author::
'"The Escrow Transactional Method," Presented at First Annual Workshop
on High Performance Transaction Systems, September 1985, later
published in ACM Transactions on Database Systems, V. 11, No. 4,
December 1986,pp. 405-430. This has been an influential paper. I know
of nearly 30 citations to the Escrow Transactions paper in the
literature including a series of papers by different authors extending
the Escrow method to database replication. Authors of these papers
include: Theo Haerder, Akhil Kumar and Michael Stonebraker, N.
Soparkar and Avi Silberschats, Daniel Barbar-Mill and Hector
Garcia-Molina.'
http://www.cs.umb.edu/~poneil/EscrowTM.pdf

And here's another from OASIS BTP:
http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=business-transaction

<excerpt>
In general, to be able to satisfy such contracts a BTP-enabled service
must support in some
manner provisional or tentative state changes (the transaction�s
Provisional Effect) and
completion either through confirmation (Final Effect) or cancellation
(Counter-effect). The
meaning of provisional, final, and Counter-effect are specific to the
application and to the
implementation of the application.
[...]
���������� Table 1 Some alternatives for Provisional, Final and Counter-Effects
------------------------------

Provisional Effect:
Perform the changes, making them visible; store information to undo the changes

Final Effect::
Delete undo information

 Counter effect:
Perform undo action

Comment:
One form of compensation approach

-----------------------------------------------------

Provisional Effect:
Perform the changes, marked or typed as provisional, making them visible

Final Effect::
Mark or transform as final

 Counter effect:
Delete or mark/transform as cancelled

Comment:
E.g. quote-to-order cycle
</excerpt>

Hi Bob,

I'm aware of the research, and with BTP. I just want to point out that while this is an interesting theory, it has not been proven in practice.  Also I wanted to correct the terminology.

Another interesting theory that hasn't worked out in practice is three-phase commit. This does actually solve a known problem with two-phase commit (the uncertainty phase) but it isn't practical.

I don't know that the so called "provisional transactions" solve a real problem, although the idea is interesting.  I also know it was a centerpiece of BTP, which has not been adopted.

With respect to "undo" - the problem is that we need to be precise about the terms we're using to describe transactions.  I am going to assume we are discussing "technical" transactions rather than "logical" transactions - i.e. the way in which the transaction paradigm is implemented in software.  This is a very important point, because any suggestion of a new capability has to take into account existing implementations (something BTP didn't really do very well BTW).

In current practice, a transaction is the execution of a program that operates on shared data, typically on behalf of an online user. The program either runs to completion and the results are permanent, or the program does not complete and the results are discarded.  A transaction has no meaning unless it is operating on data, since it's purpose is to reliably change the state of the shared data, without leaving any partial results in the case of a crash or other failure.  Thus, there is no such thing  as a "partial" transaction in today's world.

The term "undo" refers to one mechanism that ensures that there are no partial results, by undoing the "temporary" writes to a database or other transactional resource manager that are typically done in place for better performance (i.e the assumption is that a commit is a more likely to occur than an abort) when a failure occurs. The undo mechanism relies on writing the "before" state of the resource manager's data to a recovery of undo log, from which it can be retrieved and restored if necessary.

The term "compensation" refers to a separate transaction that is run only after a previous transaction has already run to completion, in fact only after a previous transaction has committed. Because the definition of a commit includes the assumption that the results are permanent, the only way to change the results is to run another transaction (which is called a compensating transaction when it reverses or as you say undoes the results of a prior transaction).  Compensation is not undo - the key difference is that undo runs before commit, and compensation runs after commit.  

The fallacy in the partial transaction or reservation pattern is that partial results are visible.  No results are visible until after commit - this is the way things work in practice, and to suggest otherwise ignores reality.

Now if you compare the reservation pattern to a saga, that's is a reference to an accepted pattern.  Compensation is used in this pattern exactly as I describe it, to reverse the results of a prior commit. A saga is just a string of individual transactions that commit or abort separately.  They may have a logical relationship, but there is no transaction mechanism that joins them together.  A saga is typically done to avoid maintaining locks over a long sequence of operations on data, and this is fine and works.  But it also requires the developer to write specific compensation transactions for each step in the saga. No automatic mechanism exists for this.  

The problem is the suggestion that a partial result of a transaction is possible.  It is not. A transaction either commits or aborts.  If you run multiple transactions in sequence (as in a saga) they are related only logically, not in the transaction paradigm.  If you run a "provisional" transaction it has exactly the same behavior as a "final" transaction.

I just don't want anyone thinking this theory represents actual practice. 

Eric




----- Original Message ----
From: Bob Haugen <bob.haugen@...>
To: rest-discuss <rest-discuss@yahoogroups.com>
Sent: Thu, January 7, 2010 6:49:37 AM
Subject: Re: [rest-discuss] A different approach to supporting transactions  over HTTP

I should probably explain that Eric Newcomer is an expert in
transactions and I am not.  Nevertheless, I disagree, and will cite
some other transaction experts (below).

(And I promised to myself I would stop engaging in this thread, but whatever...)

(And yes this level of transactional detail is probably off-topic for
REST-discuss so I will shut up now...)

On Wed, Jan 6, 2010 at 7:49 PM, Eric Newcomer <e_newcomer@...> wrote:
>
> Compensation is not the same as undo, that is a big error in this discussion.

Compensation has been used as undo, as a replacement for cancel or
abort in the 2nd phase of 2PC, in several transactional methods,
including BTP (below) and Sagas:
www.cs.cornell.edu/andru/cs711/2002fa/reading/sagas.pdf

"To amend partial executions, each saga T, should be provided with a
compensating transaction C. The compensating transaction undoes, from
a semantic point of view, any of the actions performed by T, but does
not necessarily return the database to the state that existed when the
execution of T began."

> A similar bit of bad logic is involved in the idea of a "provisional" transaction.  I realize this idea has been around for a while, and there are several proponents of it. However a transaction is a transaction, and either it is complete or it is not complete and is rolled back (or undone). If you want to model two transactions, that's fine, but don't call one "provisional" when it has the exact same semantics as the "real" transaction.
>

That is an inaccurate representatiton of the provisional-final
pattern, leaving off the "final" part (the 2nd phase).

Here's one fairly early version. The paper is introduced by its author::
'"The Escrow Transactional Method," Presented at First Annual Workshop
on High Performance Transaction Systems, September 1985, later
published in ACM Transactions on Database Systems, V. 11, No. 4,
December 1986,pp. 405-430. This has been an influential paper. I know
of nearly 30 citations to the Escrow Transactions paper in the
literature including a series of papers by different authors extending
the Escrow method to database replication. Authors of these papers
include: Theo Haerder, Akhil Kumar and Michael Stonebraker, N.
Soparkar and Avi Silberschats, Daniel Barbar-Mill and Hector
Garcia-Molina.'
http://www.cs.umb.edu/~poneil/EscrowTM.pdf

And here's another from OASIS BTP:
http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=business-transaction

<excerpt>
In general, to be able to satisfy such contracts a BTP-enabled service
must support in some
manner provisional or tentative state changes (the transaction’s
Provisional Effect) and
completion either through confirmation (Final Effect) or cancellation
(Counter-effect). The
meaning of provisional, final, and Counter-effect are specific to the
application and to the
implementation of the application.
[...]
           Table 1 Some alternatives for Provisional, Final and Counter-Effects
------------------------------

Provisional Effect:
Perform the changes, making them visible; store information to undo the changes

Final Effect::
Delete undo information

Counter effect:
Perform undo action

Comment:
One form of compensation approach

-----------------------------------------------------

Provisional Effect:
Perform the changes, marked or typed as provisional, making them visible

Final Effect::
Mark or transform as final

Counter effect:
Delete or mark/transform as cancelled

Comment:
E.g. quote-to-order cycle
</excerpt>


------------------------------------

Yahoo! Groups Links




      

WS-REST 2010
http://ws-rest.org/
Paper Submission: February 8, 2010

Call for Papers

The First International Workshop on RESTful Design (WS-REST 2010) aims to provide a forum for discussion and dissemination of research on the emerging resource-oriented style of Web service design.

Background

Over the past few years, several discussions between advocates of the two major architectural styles for designing and implementing Web services (the RPC/ESB-oriented approach and the resource-oriented approach) have been mainly held outside of the research and academic community, within dedicated mailing lists, forums and practitioner communities. The RESTful approach to Web services has also received a significant amount of attention from industry as indicated by the numerous technical books being published on the topic.

This first edition of WS-REST, co-located with the WWW2010 conference, aims at providing an academic forum for discussing current emerging research topics centered around the application of REST, as well as advanced application scenarios for building large scale distributed systems.

In addition to presentations on novel applications of RESTful Web services technologies, the workshop program will also include discussions on the limits of the applicability of the REST architectural style, as well as recent advances in research that aim at tackling new problems that may require to extend the basic REST architectural style. The organizers are seeking novel and original, high quality paper submissions on research contributions focusing on the following topics:

    * Applications of the REST architectural style to novel domains
    * Design Patterns and Anti-Patterns for RESTful services
    * RESTful service composition
    * Inverted REST (REST for push events)
    * Integration of Pub/Sub with REST
    * Performance and QoS Evaluations of RESTful services
    * REST compliant transaction models
    * Mashups
    * Frameworks and toolkits for RESTful service implementations
    * Frameworks and toolkits for RESTful service consumption
    * Modeling RESTful services
    * Resource Design and Granularity
    * Evolution of RESTful services
    * Versioning and Extension of REST APIs
    * HTTP extensions and replacements
    * REST compliant protocols beyond HTTP
    * Multi-Protocol REST (REST architectures across protocols)

All workshop papers are peer-reviewed and accepted papers will be published as part of the ACM Digital Library. Two kinds of contributions are sought: short position papers (not to exceed 4 pages in ACM style format) describing particular challenges or experiences relevant to the scope of the workshop, and full research papers (not to exceed 8 pages in the ACM style format) describing novel solutions to relevant problems. Technology demonstrations are particularly welcome, and we encourage authors to focus on "lessons learned" rather than describing an implementation.

Papers must be submitted electronically in PDF format. Submit at the WS-REST 2010 EasyChair installation

http://www.easychair.org/conferences/?conf=WSREST2010

Important Dates

    * Submission deadline: February 8, 2010, 23.59 Hawaii time
    * Notification of acceptance: March 1, 2010
    * Camera-ready versions of accepted papers: March 14, 2010
    * WS-REST 2010 Workshop: April 26, 2010

Program Committee Chairs

    * Cesare Pautasso, Faculty of Informatics, USI Lugano, Switzerland
    * Erik Wilde, School of Information, UC Berkeley, USA
    * Alexandros Marinos, Faculty of Engineering & Physical Sciences, University of Surrey, UK

Program Committee

    * Rosa Alarcon, Pontificia Universidad Catolica de Chile
    * Subbu Allamaraju, Yahoo Inc., USA
    * Tim Bray, Sun Microsystems, USA
    * Bill Burke, Red Hat, USA
    * Benjamin Carlyle, Australia
    * Stuart Charlton, Elastra, USA
    * Joe Gregorio, Google, USA
    * Michael Hausenblas, DERI, Ireland
    * Rohit Khare, 4K Associates, USA
    * Frank Leymann, University of Stuttgart, Germany
    * Mark Nottingham, Yahoo Inc., Australia
    * Aristotle Pagaltzis, Germany
    * Ian Robinson, Thoughtworks, USA
    * Richard Taylor, UC Irvine, USA
    * Stefan Tilkov, innoQ, Germany
    * Steve Vinoski, Verivue, USA
    * Jim Webber, Thoughtworks, USA
    * Olaf Zimmermann, IBM Zurich Research Lab, Switzerland

Contact

WS-REST Web site: http://ws-rest.org/
WS-REST Email: chairs@ws-rest.org

Bob:

Thanks for the pointers to Saga and Escrow. I'm famliar with the Saga
paper and it influenced by thinking in working up the pattern
described in my post, but was not able to find a freely-available PDF
as a reference (I used a more "lightweight" description as a ref in my
post).

I'll review the Escrow paper this week.

mca
http://amundsen.com/blog/




On Thu, Jan 7, 2010 at 06:49, Bob Haugen <bob.haugen@...> wrote:
> I should probably explain that Eric Newcomer is an expert in
> transactions and I am not. �Nevertheless, I disagree, and will cite
> some other transaction experts (below).
>
> (And I promised to myself I would stop engaging in this thread, but whatever...)
>
> (And yes this level of transactional detail is probably off-topic for
> REST-discuss so I will shut up now...)
>
> On Wed, Jan 6, 2010 at 7:49 PM, Eric Newcomer <e_newcomer@...> wrote:
>>
>> Compensation is not the same as undo, that is a big error in this discussion.
>
> Compensation has been used as undo, as a replacement for cancel or
> abort in the 2nd phase of 2PC, in several transactional methods,
> including BTP (below) and Sagas:
> www.cs.cornell.edu/andru/cs711/2002fa/reading/sagas.pdf
>
> "To amend partial executions, each saga T, should be provided with a
> compensating transaction C. The compensating transaction undoes, from
> a semantic point of view, any of the actions performed by T, but does
> not necessarily return the database to the state that existed when the
> execution of T began."
>
>> A similar bit of bad logic is involved in the idea of a "provisional" transaction.� I realize this idea has been around for a while, and there are several proponents of it. However a transaction is a transaction, and either it is complete or it is not complete and is rolled back (or undone). If you want to model two transactions, that's fine, but don't call one "provisional" when it has the exact same semantics as the "real" transaction.
>>
>
> That is an inaccurate representatiton of the provisional-final
> pattern, leaving off the "final" part (the 2nd phase).
>
> Here's one fairly early version. The paper is introduced by its author::
> '"The Escrow Transactional Method," Presented at First Annual Workshop
> on High Performance Transaction Systems, September 1985, later
> published in ACM Transactions on Database Systems, V. 11, No. 4,
> December 1986,pp. 405-430. This has been an influential paper. I know
> of nearly 30 citations to the Escrow Transactions paper in the
> literature including a series of papers by different authors extending
> the Escrow method to database replication. Authors of these papers
> include: Theo Haerder, Akhil Kumar and Michael Stonebraker, N.
> Soparkar and Avi Silberschats, Daniel Barbar-Mill and Hector
> Garcia-Molina.'
> http://www.cs.umb.edu/~poneil/EscrowTM.pdf
>
> And here's another from OASIS BTP:
> http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=business-transaction
>
> <excerpt>
> In general, to be able to satisfy such contracts a BTP-enabled service
> must support in some
> manner provisional or tentative state changes (the transaction�s
> Provisional Effect) and
> completion either through confirmation (Final Effect) or cancellation
> (Counter-effect). The
> meaning of provisional, final, and Counter-effect are specific to the
> application and to the
> implementation of the application.
> [...]
> ���������� Table 1 Some alternatives for Provisional, Final and Counter-Effects
> ------------------------------
>
> Provisional Effect:
> Perform the changes, making them visible; store information to undo the changes
>
> Final Effect::
> Delete undo information
>
> �Counter effect:
> Perform undo action
>
> Comment:
> One form of compensation approach
>
> -----------------------------------------------------
>
> Provisional Effect:
> Perform the changes, marked or typed as provisional, making them visible
>
> Final Effect::
> Mark or transform as final
>
> �Counter effect:
> Delete or mark/transform as cancelled
>
> Comment:
> E.g. quote-to-order cycle
> </excerpt>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

Hello,

Have you looked at the pointer Mark Mc Keown sent a few weeks ago on 
this list:
- http://tech.dir.groups.yahoo.com/group/rest-discuss/message/14035
- 
http://betathoughts.blogspot.com/2007/06/brief-history-of-consensus-2pc-and.html
- http://www.allhands.org.uk/2006/proceedings/papers/624.pdf

The initial application was the co-allocation of resources. It uses the 
Paxos-commit algorithm.

Best wishes,

Bruno.


mike amundsen wrote:
>  
> 
> I've posted "DOCTR: a better approach to HTTP transactions" to my blog
> (http://amundsen.com/blog/archives/1024 
> <http://amundsen.com/blog/archives/1024>) and welcome any feedback.
> 
> Some excerpts:
> 
> <snip>
> A better approach is to expose an HTTP-compliant transaction service
> interface (TSI) that takes advantage of the protocol's inherent
> architectural style. Transactions over HTTP should be optional,
> discoverable, negotiable, based on optimistic commits, and (in the
> case of failures) use compenstating requests as a way to reverse
> previous work.
> </snip>
> 
> and
> 
> <snip>
> What is described here is a transaction service interface (TSI) that
> clients and servers can choose to implement in ways all parties can
> agree upon. This is the way media-types are currenly handled and TSIs
> could be defined, documented, and registered in much the same way.
> This includes the possibility of registering a media-type that matches
> the TSI implementation. True to the archetictural style of the HTTP
> protocol, this approach proposes a "uniform interface" for handling
> units of work over HTTP.
> </snip>
> 
> Thanks in advance.

In [1] Roy writes

"A REST API should spend almost all of its descriptive effort in  
defining the media type(s) used for representing resources and driving  
application state, or in defining extended relation names and/or  
hypertext-enabled mark-up for existing standard media types. [...]"

Maybe I am reading too much into this, but then...usually Roy chooses  
his words quite carefully:

Does anyone know why it is "*almost* all of its descriptive effort"  
and not simply "all of its descriptive effort"? What else is there to  
be described than the media types?

Jan


[1] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

The media type definition says what methods do.  In most cases there's
plenty of wiggle-room on response codes, so that's left to the API to
describe.  A system's security implementation isn't described by its
media types, so your API has to describe the use of HTTP Digest, user
roles, and such.  Your API does this via hypertext -- descriptive error
responses with links instead of the default 4xx response message, for
example.

-Eric

> 
> In [1] Roy writes
> 
> "A REST API should spend almost all of its descriptive effort in  
> defining the media type(s) used for representing resources and
> driving application state, or in defining extended relation names
> and/or hypertext-enabled mark-up for existing standard media types.
> [...]"
> 
> Maybe I am reading too much into this, but then...usually Roy
> chooses his words quite carefully:
> 
> Does anyone know why it is "*almost* all of its descriptive effort"  
> and not simply "all of its descriptive effort"? What else is there
> to be described than the media types?
> 
> Jan
> 
> 
> [1]
> http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
> 

On 7 Jan 2010 13:03, "Eric Newcomer" <e_newcomer@...> wrote:



Hi Bob,

I'm aware of the research, and with BTP. I just want to point out that while
this is an interesting theory, it has not been proven in practice. Also I
wanted to correct the terminology.

Another interesting theory that hasn't worked out in practice is three-phase
commit. This does actually solve a known problem with two-phase commit (the
uncertainty phase) but it isn't practical.

I don't know that the so called "provisional transactions" solve a real
problem, although the idea is interesting. I also know it was a centerpiece
of BTP, which has not been adopted.

With respect to "undo" - the problem is that we need to be precise about the
terms we're using to describe transactions. I am going to assume we are
discussing "technical" transactions rather than "logical" transactions -
i.e. the way in which the transaction paradigm is implemented in software.
This is a very important point, because any suggestion of a new capability
has to take into account existing implementations (something BTP didn't
really do very well BTW).

In current practice, a transaction is the execution of a program that
operates on shared data, typically on behalf of an online user. The program
either runs to completion and the results are permanent, or the program does
not complete and the results are discarded. A transaction has no meaning
unless it is operating on data, since it's purpose is to reliably change the
state of the shared data, without leaving any partial results in the case of
a crash or other failure. Thus, there is no such thing as a "partial"
transaction in today's world.

The term "undo" refers to one mechanism that ensures that there are no
partial results, by undoing the "temporary" writes to a database or other
transactional resource manager that are typically done in place for better
performance (i.e the assumption is that a commit is a more likely to occur
than an abort) when a failure occurs. The undo mechanism relies on writing
the "before" state of the resource manager's data to a recovery of undo log,
from which it can be retrieved and restored if necessary.

The term "compensation" refers to a separate transaction that is run only
after a previous transaction has already run to completion, in fact only
after a previous transaction has committed. Because the definition of a
commit includes the assumption that the results are permanent, the only way
to change the results is to run another transaction (which is called a
compensating transaction when it reverses or as you say undoes the results
of a prior transaction). Compensation is not undo - the key difference is
that undo runs before commit, and compensation runs after commit.

The fallacy in the partial transaction or reservation pattern is that
partial results are visible. No results are visible until after commit -
this is the way things work in practice, and to suggest otherwise ignores
reality.

Now if you compare the reservation pattern to a saga, that's is a reference
to an accepted pattern. Compensation is used in this pattern exactly as I
describe it, to reverse the results of a prior commit. A saga is just a
string of individual transactions that commit or abort separately. They may
have a logical relationship, but there is no transaction mechanism that
joins them together. A saga is typically done to avoid maintaining locks
over a long sequence of operations on data, and this is fine and works. But
it also requires the developer to write specific compensation transactions
for each step in the saga. No automatic mechanism exists for this.

The problem is the suggestion that a partial result of a transaction is
possible. It is not. A transaction either commits or aborts. If you run
multiple transactions in sequence (as in a saga) they are related only
logically, not in the transaction paradigm. If you run a "provisional"
transaction it has exactly the same behavior as a "final" transaction.

I just don't want anyone thinking this theory represents actual practice.

Eric

----- Original Message ---- From: Bob Haugen <bob.haugen@...>

To: rest-discuss <rest-discuss@yahoogroups.com> Sent: Thu, January 7, 2010
6:49:37 AM Subject: Re: [...

I should probably explain that Eric Newcomer is an expert in transactions
and I am not. Nevertheless...
 

This is a very interesting post, clear, concise, to the point, I think I
learned more about transactions and compensation with this then with entire
books on the subject. You should consider writing this as a article or blog
entry as for future reference.

Cheers.

On 7 Jan 2010 13:03, "Eric Newcomer" <e_newcomer@...> wrote:



Hi Bob,

I'm aware of the research, and with BTP. I just want to point out that while
this is an interesting theory, it has not been proven in practice. Also I
wanted to correct the terminology.

Another interesting theory that hasn't worked out in practice is three-phase
commit. This does actually solve a known problem with two-phase commit (the
uncertainty phase) but it isn't practical.

I don't know that the so called "provisional transactions" solve a real
problem, although the idea is interesting. I also know it was a centerpiece
of BTP, which has not been adopted.

With respect to "undo" - the problem is that we need to be precise about the
terms we're using to describe transactions. I am going to assume we are
discussing "technical" transactions rather than "logical" transactions -
i.e. the way in which the transaction paradigm is implemented in software.
This is a very important point, because any suggestion of a new capability
has to take into account existing implementations (something BTP didn't
really do very well BTW).

In current practice, a transaction is the execution of a program that
operates on shared data, typically on behalf of an online user. The program
either runs to completion and the results are permanent, or the program does
not complete and the results are discarded. A transaction has no meaning
unless it is operating on data, since it's purpose is to reliably change the
state of the shared data, without leaving any partial results in the case of
a crash or other failure. Thus, there is no such thing as a "partial"
transaction in today's world.

The term "undo" refers to one mechanism that ensures that there are no
partial results, by undoing the "temporary" writes to a database or other
transactional resource manager that are typically done in place for better
performance (i.e the assumption is that a commit is a more likely to occur
than an abort) when a failure occurs. The undo mechanism relies on writing
the "before" state of the resource manager's data to a recovery of undo log,
from which it can be retrieved and restored if necessary.

The term "compensation" refers to a separate transaction that is run only
after a previous transaction has already run to completion, in fact only
after a previous transaction has committed. Because the definition of a
commit includes the assumption that the results are permanent, the only way
to change the results is to run another transaction (which is called a
compensating transaction when it reverses or as you say undoes the results
of a prior transaction). Compensation is not undo - the key difference is
that undo runs before commit, and compensation runs after commit.

The fallacy in the partial transaction or reservation pattern is that
partial results are visible. No results are visible until after commit -
this is the way things work in practice, and to suggest otherwise ignores
reality.

Now if you compare the reservation pattern to a saga, that's is a reference
to an accepted pattern. Compensation is used in this pattern exactly as I
describe it, to reverse the results of a prior commit. A saga is just a
string of individual transactions that commit or abort separately. They may
have a logical relationship, but there is no transaction mechanism that
joins them together. A saga is typically done to avoid maintaining locks
over a long sequence of operations on data, and this is fine and works. But
it also requires the developer to write specific compensation transactions
for each step in the saga. No automatic mechanism exists for this.

The problem is the suggestion that a partial result of a transaction is
possible. It is not. A transaction either commits or aborts. If you run
multiple transactions in sequence (as in a saga) they are related only
logically, not in the transaction paradigm. If you run a "provisional"
transaction it has exactly the same behavior as a "final" transaction.

I just don't want anyone thinking this theory represents actual practice.

Eric

----- Original Message ---- From: Bob Haugen <bob.haugen@...>

To: rest-discuss <rest-discuss@yahoogroups.com> Sent: Thu, January 7, 2010
6:49:37 AM Subject: Re: [...

I should probably explain that Eric Newcomer is an expert in transactions
and I am not. Nevertheless...
 

On Jan 7, 2010, at 8:58 PM, Eric J. Bowman wrote:

> The media type definition says what methods do.  In most cases there's
> plenty of wiggle-room on response codes, so that's left to the API to
> describe.

No, the error codes need no description - they are fully described by  
RFC 2616.


>  A system's security implementation isn't described by its
> media types, so your API has to describe the use of HTTP Digest, user
> roles, and such.  Your API does this via hypertext -- descriptive  
> error
> responses with links instead of the default 4xx response message, for
> example.
>

I was referring to design time documentation, not runtime.

What does a service description need besides describing what the set  
of media types (and link rels etc) is, it uses?


Jan


> -Eric
>
>>
>> In [1] Roy writes
>>
>> "A REST API should spend almost all of its descriptive effort in
>> defining the media type(s) used for representing resources and
>> driving application state, or in defining extended relation names
>> and/or hypertext-enabled mark-up for existing standard media types.
>> [...]"
>>
>> Maybe I am reading too much into this, but then...usually Roy
>> chooses his words quite carefully:
>>
>> Does anyone know why it is "*almost* all of its descriptive effort"
>> and not simply "all of its descriptive effort"? What else is there
>> to be described than the media types?
>>
>> Jan
>>
>>
>> [1]
>> http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
>>

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

Hi Folks,

I am seeking examples of websites that don't have a URL for each webpage.

Let me illustrate: I type into my browser the URL to the website. I then see its homepage, which contains links. I click on a link and it gives me a new page, but the URL doesn't change. I continue clicking on links and the URL remains the same throughout my visit to the website.

Can you provide an example website?

/Roger

Lots of the Google GWT-based or otherwise AJAXified products like  
Gmail, Google Calendar, and Google Reader have this sort of behavior.

Jon
........
Jon Moore


On Jan 8, 2010, at 7:59 AM, "Costello, Roger L." <costello@mitre.org>  
wrote:

> Hi Folks,
>
> I am seeking examples of websites that don't have a URL for each  
> webpage.
>
> Let me illustrate: I type into my browser the URL to the website. I  
> then see its homepage, which contains links. I click on a link and  
> it gives me a new page, but the URL doesn't change. I continue  
> clicking on links and the URL remains the same throughout my visit  
> to the website.
>
> Can you provide an example website?
>
> /Roger
> 

Flex/flash based ones also, although they can play around with anchors, they
usually do not create real pages: http://www.tucano.org.br/portal.html
Everything you click is an anchor, not another web page, therefore google
can not index it.

Guilherme Silveira
Caelum | Ensino e Inova��o
http://www.caelum.com.br/


On Fri, Jan 8, 2010 at 11:28 AM, Moore, Jonathan (CIM) <
jonathan_moore@...> wrote:

>
>
> Lots of the Google GWT-based or otherwise AJAXified products like Gmail,
> Google Calendar, and Google Reader have this sort of behavior.
>
> Jon
> ........
> Jon Moore
>
>
> On Jan 8, 2010, at 7:59 AM, "Costello, Roger L." <costello@...>
> wrote:
>
>
>
> Hi Folks,
>
> I am seeking examples of websites that don't have a URL for each webpage.
>
> Let me illustrate: I type into my browser the URL to the website. I then
> see its homepage, which contains links. I click on a link and it gives me a
> new page, but the URL doesn't change. I continue clicking on links and the
> URL remains the same throughout my visit to the website.
>
> Can you provide an example website?
>
> /Roger
>
>   
>

On Fri, Jan 8, 2010 at 9:24 AM, Guilherme Silveira <
guilherme.silveira@...> wrote:

>
>
> Flex/flash based ones also, although they can play around with anchors,
> they usually do not create real pages:
> http://www.tucano.org.br/portal.html
> Everything you click is an anchor, not another web page, therefore google
> can not index it.
>
>
There are also web application where almost every page is a form that POSTs
back to the same never-changing URL. Even "links" that you click actually
just run javascript to submit the form.

> There are also web application where almost every page is a form that POSTs
> back to the same never-changing URL. Even "links" that you click actually
> just run javascript to submit the form.
Some touch of irony? :)

Regards

going all the way round and almost back to the start again :

http://code.quirkey.com/sammy/

... perhaps ?

>
> On Fri, Jan 8, 2010 at 9:24 AM, Guilherme Silveira <guilherme.silveira@...
> > wrote:
>
> Flex/flash based ones also, although they can play around with 
> anchors, they usually do not create real pages: http://www.tucano.org.br/portal.html
>
> Everything you click is an anchor, not another web page, therefore 
> google can not index it.
>
>
> There are also web application where almost every page is a form 
> that POSTs back to the same never-changing URL. Even "links" that 
> you click actually just run javascript to submit the form.
>
> 


Roger Menday (PhD)
<roger.menday@...>

Senior Researcher, Fujitsu Laboratories of Europe Limited
Hayes Park Central, Hayes End Road, Hayes, Middlesex, UB4 8FE, U.K.
Tel: +44 (0) 208 606 4534



______________________________________________________________________
                                       
 Fujitsu Laboratories of Europe Limited
 Hayes Park Central, Hayes End Road, Hayes, Middlesex, UB4 8FE
 Registered No. 4153469

 This e-mail and any attachments are for the sole use of addressee(s) and
 may contain information which is privileged and confidential. Unauthorised
 use or copying for disclosure is strictly prohibited. The fact that this
 e-mail has been scanned by Trendmicro Interscan and McAfee Groupshield does
 not guarantee that it has not been intercepted or amended nor that it is
 virus-free.

On Jan 8, 2010, at 6:30 AM, Guilherme Silveira wrote:

>> There are also web application where almost every page is a form that POSTs
>> back to the same never-changing URL. Even "links" that you click actually
>> just run javascript to submit the form.
> Some touch of irony? :)

I am told that lots of enterprises continue to pay a hefty ransom to some of the innovative frameworks that thought it is really cool to have a single URI for an entire site.

Subbu

Jan Algermissen wrote:
> 
> On Jan 7, 2010, at 8:58 PM, Eric J. Bowman wrote:
> 
> > The media type definition says what methods do.  In most cases
> > there's plenty of wiggle-room on response codes, so that's left to
> > the API to describe.
> 
> No, the error codes need no description - they are fully described
> by RFC 2616.
>

Please see sections 4.4 and 5.5 of RFC 5023.  Response codes are indeed
described by HTTP, that isn't the issue.  The issue is what response is
issued to what request, and that isn't defined by media type.  My Atom
Protocol implementation may respond 202 Accepted instead of 201 Created
because I've implemented moderation of new content.  Only my API can
describe that authoritatively.

> 
> >  A system's security implementation isn't described by its
> > media types, so your API has to describe the use of HTTP Digest,
> > user roles, and such.  Your API does this via hypertext --
> > descriptive error
> > responses with links instead of the default 4xx response message,
> > for example.
> >
> 
> I was referring to design time documentation, not runtime.
> 

I know you were.  But, a REST system combines self-descriptive
messaging with a self-documenting API.  You can write out-of-band
documentation for it to your heart's content.  But that documentation
ought to be reflected at runtime, so I can know exactly how your system
works by stepping my way through it using curl or a protocol analyzer,
without having to constantly refer to the design-time documentation.

-Eric

Roger Menday wrote:
>
>
>
> going all the way round and almost back to the start again :
>
> http://code.quirkey.com/sammy/
>
> ... perhaps ? 
>

sammy.js is just a nifty way of controlling client state using html and 
javascript.. what's wrong with that? It's code on demand

>>
>> On Fri, Jan 8, 2010 at 9:24 AM, Guilherme 
>> Silveira <guilherme.silveira@... 
>> <mailto:guilherme.silveira@...>> wrote:
>>
>>      
>>
>>     Flex/flash based ones also, although they can play around with
>>     anchors, they usually do not create real
>>     pages: http://www.tucano.org.br/portal.html
>>     <http://www.tucano.org.br/portal.html>
>>
>>     Everything you click is an anchor, not another web page,
>>     therefore google can not index it.
>>
>>
>> There are also web application where almost every page is a form that 
>> POSTs back to the same never-changing URL. Even "links" that you 
>> click actually just run javascript to submit the form.
>>
>
>
> Roger Menday (PhD)
> <roger.menday@... <mailto:roger.menday@...>>
>
> Senior Researcher, Fujitsu Laboratories of Europe Limited
> Hayes Park Central, Hayes End Road, Hayes, Middlesex, UB4 8FE, U.K.
> Tel: +44 (0) 208 606 4534

On Jan 8, 2010, at 9:46 PM, Eric J. Bowman wrote:

> Jan Algermissen wrote:
>>
>> On Jan 7, 2010, at 8:58 PM, Eric J. Bowman wrote:
>>
>>> The media type definition says what methods do.  In most cases
>>> there's plenty of wiggle-room on response codes, so that's left to
>>> the API to describe.
>>
>> No, the error codes need no description - they are fully described
>> by RFC 2616.
>>
>
> Please see sections 4.4 and 5.5 of RFC 5023.

I know - but RFC 5023 should actually not do that.

>  Response codes are indeed
> described by HTTP, that isn't the issue.  The issue is what response  
> is
> issued to what request, and that isn't defined by media type.

No, it is completely up to the server. The server may respond in any  
way, as long as the response is correctly telling the client what  
happened (e.g. send 201 when a resource has been created). The  
examples in RFC 5023 do actually tell you nothing about how a given  
server might choose to respond.

> My Atom
> Protocol implementation may respond 202 Accepted instead of 201  
> Created
> because I've implemented moderation of new content.  Only my API can
> describe that authoritatively.

No, RFC2616 describes what has to happen. Return 201 upon creation and  
202 if the request has been accepted but not yet been processed.


>
>>
>>> A system's security implementation isn't described by its
>>> media types, so your API has to describe the use of HTTP Digest,
>>> user roles, and such.  Your API does this via hypertext --
>>> descriptive error
>>> responses with links instead of the default 4xx response message,
>>> for example.
>>>
>>
>> I was referring to design time documentation, not runtime.
>>
>
> I know you were.  But, a REST system combines self-descriptive
> messaging with a self-documenting API.

What is a 'self documenting API'?

>  You can write out-of-band
> documentation for it to your heart's content.  But that documentation
> ought to be reflected at runtime, so I can know exactly how your  
> system
> works by stepping my way through it using curl or a protocol analyzer,

You can never know from observing an interaction at a given time how  
the server might respond the next time.


> without having to constantly refer to the design-time documentation.

What 'design time documentation' are you refering to?

Jan



>
> -Eric

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

On 8 Jan 2010, at 21:05, Mike Kelly wrote:

> Roger Menday wrote:
>>
>>
>>
>> going all the way round and almost back to the start again :
>>
>> http://code.quirkey.com/sammy/
>>
>> ... perhaps ?
>
> sammy.js is just a nifty way of controlling client state using html  
> and javascript.. what's wrong with that?

i wasn't saying there was anything wrong with it - i rather like infact.

> It's code on demand
>
>>>
>>> On Fri, Jan 8, 2010 at 9:24 AM, Guilherme Silveira <guilherme.silveira@... 
>>>  <mailto:guilherme.silveira@...>> wrote:
>>>
>>>
>>>    Flex/flash based ones also, although they can play around with
>>>    anchors, they usually do not create real
>>>    pages: http://www.tucano.org.br/portal.html
>>>    <http://www.tucano.org.br/portal.html>
>>>
>>>    Everything you click is an anchor, not another web page,
>>>    therefore google can not index it.
>>>
>>>
>>> There are also web application where almost every page is a form  
>>> that POSTs back to the same never-changing URL. Even "links" that  
>>> you click actually just run javascript to submit the form.
>>>
>>
>>
>> Roger Menday (PhD)
>> <roger.menday@... <mailto:roger.menday@...>>
>>
>> Senior Researcher, Fujitsu Laboratories of Europe Limited
>> Hayes Park Central, Hayes End Road, Hayes, Middlesex, UB4 8FE, U.K.
>> Tel: +44 (0) 208 606 4534


Roger Menday (PhD)
<roger.menday@...>

Senior Researcher, Fujitsu Laboratories of Europe Limited
Hayes Park Central, Hayes End Road, Hayes, Middlesex, UB4 8FE, U.K.
Tel: +44 (0) 208 606 4534


______________________________________________________________________
                                        
 Fujitsu Laboratories of Europe Limited
 Hayes Park Central, Hayes End Road, Hayes, Middlesex, UB4 8FE
 Registered No. 4153469
 
 This e-mail and any attachments are for the sole use of addressee(s) and
 may contain information which is privileged and confidential. Unauthorised
 use or copying for disclosure is strictly prohibited. The fact that this
 e-mail has been scanned by Trendmicro Interscan and McAfee Groupshield does
 not guarantee that it has not been intercepted or amended nor that it is
 virus-free. 

Jan Algermissen wrote:
>
> > Please see sections 4.4 and 5.5 of RFC 5023.
> 
> I know - but RFC 5023 should actually not do that.
> 

Regardless, RFC 5023 is correct that RFC 2616 says exactly what I said,
about using descriptive messaging (and linking) in 4xx response bodies.
When someone wants to know what REST is, I point them to what it is not
-- every major CMS implementation out there (wiki, forum, weblog etc.)
returns a fully-styled page, either to create the resource, or a search
interface, when a document isn't found.

The problem is they all do this with a 200 OK response, when the
correct response is 404.  There's nothing wrong with a 404 page that
looks like the rest of the site, complete with menu links, offering a
variety of choices for error recovery.  I explain that changing the
response code wouldn't make the system RESTful, but it does illustrate
the idea of hypertext driving application state very well.

Is the 404 failure mode of the system a search interface (forum), or a
create new content interface (wiki)?  You can document this out-of-band
if you'd like, but this aspect of the API documents itself in hypertext,
along with all the other choices for transitioning to another steady-
state (menu links), to recover from the error.

The standard 404 response is essentially terminating the application,
the user has to back up and try something different, instead of being
instructed as to how to move forwards.  That isn't a self-documenting
API.

>
> >  Response codes are indeed
> > described by HTTP, that isn't the issue.  The issue is what
> > response is
> > issued to what request, and that isn't defined by media type.
> 
> No, it is completely up to the server. The server may respond in any  
> way, as long as the response is correctly telling the client what  
> happened (e.g. send 201 when a resource has been created). The  
> examples in RFC 5023 do actually tell you nothing about how a given  
> server might choose to respond.
> 

Exactly.  The server's response tells you how the server responded to a
hypertext interaction.  You asked what you need to document outside the
scope of a media type.  Whatever out-of-band documentation you have
should be reflective of what's actually happening in-band.  The media
type is only telling you what methods to use and how to use them, not
what the responses are going to be... wiggle-room, like I said.

>
> > My Atom
> > Protocol implementation may respond 202 Accepted instead of 201  
> > Created
> > because I've implemented moderation of new content.  Only my API can
> > describe that authoritatively.
> 
> No, RFC2616 describes what has to happen. Return 201 upon creation
> and 202 if the request has been accepted but not yet been processed.
> 

RFC 2616 tells the client how to interpret the response.  Whether the
response is a 201 or a 202 is up to your server.  Isn't this the sort
of thing you were asking about documenting, that's outside the scope of
a media type (or the protocol definition)?

>
> > I know you were.  But, a REST system combines self-descriptive
> > messaging with a self-documenting API.
> 
> What is a 'self documenting API'?
> 

Any truly RESTful API documents itself in-band.  My Xforms Atom
Protocol client (minus the PATCH stuff) is RESTful because it is
hypertext-driven. The specifics of my implementation may be deduced by
driving the hypertext application (and viewing source) in a browser
with xforms and protocol analyzer extensions.  All out-of-band knowledge
relevant to protocol interaction, is encapsulated within the media types
used, which are standard.

I use the term self-documenting, because people get confused into
thinking that payloads must be self-describing.  My use of the term
self-documenting is w3c approved:

http://www.w3.org/TR/gov-data/

Because while following their advice won't get you REST as a result,
it's at least hypertext-driven, i.e. has a self-documenting API even if
the messaging isn't self-descriptive.

>
> >  You can write out-of-band
> > documentation for it to your heart's content.  But that
> > documentation ought to be reflected at runtime, so I can know
> > exactly how your system
> > works by stepping my way through it using curl or a protocol
> > analyzer,
> 
> You can never know from observing an interaction at a given time how  
> the server might respond the next time.
> 

Of course not.  At any given time, the only authoritative information
is what the server's response is, at that time.  If your implementation
isn't bounded by your API documentation, you can change whatever you
want whenever you want, even while I'm stepping through it with a
protocol analyzer.  That's an edge case.

> 
> > without having to constantly refer to the design-time documentation.
> 
> What 'design time documentation' are you refering to?
> 

You're the one who brought it up, I assumed you knew?  Assuming a
stable implementation with documentation, I shouldn't have to rely on
your out-of-band documentation to figure out what's what.  I ought to
be able to determine everything I need to know that isn't covered by
media type or protocol definitions in-band from the hypertext.

The only authoritative source for how a server will respond to an Atom
Protocol POST request, is the server's response.  One day that response
may be 201, the next day it may change to 202.  Presumably, the user is
informed of the change using natural language somewhere on the create-
post form, that moderation is now in effect and their posts will no
longer appear instantly.  So the API documents itself in-band, and sure
enough, the change is reflected in that my protocol analyzer is no
longer receiving 201 responses to POST requests, the response code is
now 202.  If I care about why, the explanation is right there in-band.

If all out-of-band knowledge in REST is relegated to media type
definitions (except for domain-specific vocabularies presented within a
standard media type), then all other knowledge must be documented in-
band (including in-band links to definitions of domain-specific
vocabularies), right?

So that's the other thing you can document, the meaning of whatever
domain-specific ontology you're presenting using RDFa inside XHTML.
It's part of your API, though, so you should link to it in-band such
that its use is self-documenting.

-Eric

Many websites like amazon.com, show personalized pages using cookies. This is not restful as URIs do not represent the resources, but there is hidden state maintained on client side.
Roy Fielding's dissertation has following comment on cookie based state mechanism

"A state mechanism that involves preferences can be more efficiently implemented using judicious use of context-setting URI rather than cookies, where judicious means one URI per state rather than an unbounded number of URI due to the embedding of a user-id."

Are there any examples of this? In particular, what does URI per state means? 

Thanks,
Unmesh

"unmesh_joshi" wrote:
>
> Many websites like amazon.com, show personalized pages using cookies.
> This is not restful as URIs do not represent the resources, but there
> is hidden state maintained on client side. Roy Fielding's
> dissertation has following comment on cookie based state mechanism
> 
> "A state mechanism that involves preferences can be more efficiently
> implemented using judicious use of context-setting URI rather than
> cookies, where judicious means one URI per state rather than an
> unbounded number of URI due to the embedding of a user-id."
> 
> Are there any examples of this? In particular, what does URI per
> state means? 
> 

The state of the resource and the state of the application are not
always the same in REST.  A personalized page is really the same
resource state for all users, although each user's application state
varies by username.  Instead of assigning each application state a URI
like http://example.org/joe/welcome_page, use one URI per resource
state, i.e. http://example.org/welcome_page, and vary its output based
on the username present in HTTP Digest authentication headers (instead
of cookies).  That's just one example.

-Eric

>>>>> "unmesh" == unmesh joshi <unmeshjoshi@...> writes:

    unmesh> Many websites like amazon.com, show personalized pages
    unmesh> using cookies. This is not restful as URIs do not
    unmesh> represent the resources, but there is hidden state
    unmesh> maintained on client side.  Roy Fielding's dissertation
    unmesh> has following comment on cookie based state mechanism

    unmesh> "A state mechanism that involves preferences can be more
    unmesh> efficiently implemented using judicious use of
    unmesh> context-setting URI rather than cookies, where judicious
    unmesh> means one URI per state rather than an unbounded number of
    unmesh> URI due to the embedding of a user-id."

    unmesh> Are there any examples of this? In particular, what does
    unmesh> URI per state means?

In the case of a user who has logged in, personalized pages are really
easy, because you have access to the user name that is logged in
(REMOTE_USER in CGI).

So if that is set, you just do your stuff. No need for cookies, nor
need for context-setting URI.

The latter is usually implemented as a prefix/suffix in the URL.

-- 
Cheers,

Berend de Boer

Another way to handle personalization over HTTP in the Web browser
world is to return a shared representation that includes
code-on-demand that uses the current user-id to make additional
requests for resources directly associated w/ user-id.  In this way,
the application can still take advantage of shard caches for the
initial representations and private caches for the additional, user-id
specific representations.

mca
http://amundsen.com/blog/




On Fri, Jan 8, 2010 at 20:52,  <berend@...> wrote:
>>>>>> "unmesh" == unmesh joshi <unmeshjoshi@...> writes:
>
> � �unmesh> Many websites like amazon.com, show personalized pages
> � �unmesh> using cookies. This is not restful as URIs do not
> � �unmesh> represent the resources, but there is hidden state
> � �unmesh> maintained on client side. �Roy Fielding's dissertation
> � �unmesh> has following comment on cookie based state mechanism
>
> � �unmesh> "A state mechanism that involves preferences can be more
> � �unmesh> efficiently implemented using judicious use of
> � �unmesh> context-setting URI rather than cookies, where judicious
> � �unmesh> means one URI per state rather than an unbounded number of
> � �unmesh> URI due to the embedding of a user-id."
>
> � �unmesh> Are there any examples of this? In particular, what does
> � �unmesh> URI per state means?
>
> In the case of a user who has logged in, personalized pages are really
> easy, because you have access to the user name that is logged in
> (REMOTE_USER in CGI).
>
> So if that is set, you just do your stuff. No need for cookies, nor
> need for context-setting URI.
>
> The latter is usually implemented as a prefix/suffix in the URL.
>
> --
> Cheers,
>
> Berend de Boer
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

Similarly, some non-browser apps I've worked on leverage shared XML
representations containing XInclude elements that make the secondary
private requests.

mca
http://amundsen.com/blog/




> On Fri, Jan 8, 2010 at 21:19, Peter <pkeane@...> wrote:
>>
>>
>> --- In rest-discuss@yahoogroups.com, mike amundsen <mamund@...> wrote:
>>>
>>> Another way to handle personalization over HTTP in the Web browser
>>> world is to return a shared representation that includes
>>> code-on-demand that uses the current user-id to make additional
>>> requests for resources directly associated w/ user-id. �In this way,
>>> the application can still take advantage of shard caches for the
>>> initial representations and private caches for the additional, user-id
>>> specific representations.
>>>
>>
>> We do that exact thing. �The page itself is served identically to everyone, and a subsequent (ajax) request grabs some data that javascript code uses to "decorate" the page w/ personalized info. �The user id is actually stored in a cookie when the user first logs in, and on each request the js uses that user id to construct the URI used for the ajax request. �It is (I think) one of the few (basically) RESTful uses of cookies -- the resource itself (unique user data) is completely visible.
>>
>> http://tech.groups.yahoo.com/group/rest-discuss/message/10027
>>
>> Of course, you can also do http basic auth on that second request as well.
>>
>> --peter
>>
>>
>>> mca
>>> http://amundsen.com/blog/
>>>
>>>
>>>
>>>
>>> On Fri, Jan 8, 2010 at 20:52, �<berend@...> wrote:
>>> >>>>>> "unmesh" == unmesh joshi <unmeshjoshi@...> writes:
>>> >
>>> > � �unmesh> Many websites like amazon.com, show personalized pages
>>> > � �unmesh> using cookies. This is not restful as URIs do not
>>> > � �unmesh> represent the resources, but there is hidden state
>>> > � �unmesh> maintained on client side. �Roy Fielding's dissertation
>>> > � �unmesh> has following comment on cookie based state mechanism
>>> >
>>> > � �unmesh> "A state mechanism that involves preferences can be more
>>> > � �unmesh> efficiently implemented using judicious use of
>>> > � �unmesh> context-setting URI rather than cookies, where judicious
>>> > � �unmesh> means one URI per state rather than an unbounded number of
>>> > � �unmesh> URI due to the embedding of a user-id."
>>> >
>>> > � �unmesh> Are there any examples of this? In particular, what does
>>> > � �unmesh> URI per state means?
>>> >
>>> > In the case of a user who has logged in, personalized pages are really
>>> > easy, because you have access to the user name that is logged in
>>> > (REMOTE_USER in CGI).
>>> >
>>> > So if that is set, you just do your stuff. No need for cookies, nor
>>> > need for context-setting URI.
>>> >
>>> > The latter is usually implemented as a prefix/suffix in the URL.
>>> >
>>> > --
>>> > Cheers,
>>> >
>>> > Berend de Boer
>>> >
>>> >
>>> > ------------------------------------
>>> >
>>> > Yahoo! Groups Links
>>> >
>>> >
>>> >
>>> >
>>>
>>
>>
>>
>

a cookie is a client side temporary memory ... I don't see relationship with
the server side.. .

Cookies seems more like data annotation than "state" in terms of REST....

You don't need to impose REST in both sides.... after defining your service
in a way all states are reachable from an entry point, your application is
REST ... and if a client application uses tricks to mimics states it is
nothing to do with your application being REST or not.. IMHO :)



On Sat, Jan 9, 2010 at 3:41 AM, mike amundsen <mamund@...m> wrote:

>
>
> Similarly, some non-browser apps I've worked on leverage shared XML
> representations containing XInclude elements that make the secondary
> private requests.
>
>
> mca
> http://amundsen.com/blog/
>
> > On Fri, Jan 8, 2010 at 21:19, Peter <pkeane@...<pkeane%40mail.utexas.edu>>
> wrote:
>
> >>
> >>
> >> --- In rest-discuss@yahoogroups.com <rest-discuss%40yahoogroups.com>,
> mike amundsen <mamund@...> wrote:
> >>>
> >>> Another way to handle personalization over HTTP in the Web browser
> >>> world is to return a shared representation that includes
> >>> code-on-demand that uses the current user-id to make additional
> >>> requests for resources directly associated w/ user-id.  In this way,
> >>> the application can still take advantage of shard caches for the
> >>> initial representations and private caches for the additional, user-id
> >>> specific representations.
> >>>
> >>
> >> We do that exact thing.  The page itself is served identically to
> everyone, and a subsequent (ajax) request grabs some data that javascript
> code uses to "decorate" the page w/ personalized info.  The user id is
> actually stored in a cookie when the user first logs in, and on each request
> the js uses that user id to construct the URI used for the ajax request.  It
> is (I think) one of the few (basically) RESTful uses of cookies -- the
> resource itself (unique user data) is completely visible.
> >>
> >> http://tech.groups.yahoo.com/group/rest-discuss/message/10027
> >>
> >> Of course, you can also do http basic auth on that second request as
> well.
> >>
> >> --peter
>
> >>
> >>
> >>> mca
> >>> http://amundsen.com/blog/
> >>>
> >>>
> >>>
> >>>
> >>> On Fri, Jan 8, 2010 at 20:52,  <berend@...> wrote:
> >>> >>>>>> "unmesh" == unmesh joshi <unmeshjoshi@...> writes:
> >>> >
> >>> > � �unmesh> Many websites like amazon.com, show personalized
> pages
> >>> > � �unmesh> using cookies. This is not restful as URIs do not
> >>> > � �unmesh> represent the resources, but there is hidden state
> >>> > � �unmesh> maintained on client side. �Roy Fielding's
> dissertation
> >>> > � �unmesh> has following comment on cookie based state mechanism
> >>> >
> >>> > � �unmesh> "A state mechanism that involves preferences can be
> more
> >>> > � �unmesh> efficiently implemented using judicious use of
> >>> > � �unmesh> context-setting URI rather than cookies, where
> judicious
> >>> > � �unmesh> means one URI per state rather than an unbounded
> number of
> >>> > � �unmesh> URI due to the embedding of a user-id."
> >>> >
> >>> > � �unmesh> Are there any examples of this? In particular, what
> does
> >>> > � �unmesh> URI per state means?
>
> >>> >
> >>> > In the case of a user who has logged in, personalized pages are
> really
> >>> > easy, because you have access to the user name that is logged in
> >>> > (REMOTE_USER in CGI).
> >>> >
> >>> > So if that is set, you just do your stuff. No need for cookies, nor
> >>> > need for context-setting URI.
> >>> >
> >>> > The latter is usually implemented as a prefix/suffix in the URL.
> >>> >
> >>> > --
> >>> > Cheers,
> >>> >
> >>> > Berend de Boer
> >>> >
> >>> >
> >>> > ------------------------------------
> >>> >
> >>> > Yahoo! Groups Links
> >>> >
> >>> >
> >>> >
> >>> >
> >>>
> >>
> >>
> >>
> >
>  
>



-- 
------------------------------------------
  Felipe Ga�cho
  10+ Java Programmer
  CEJUG Senior Advisor

On Jan 9, 2010, at 1:01 AM, Eric J. Bowman wrote:

>  Assuming a
> stable implementation with documentation, I shouldn't have to rely on
> your out-of-band documentation to figure out what's what.

Well, you surely need media type specifications as out-of-band  
documentation. I have just been asking which documentation you need  
besides that - because Roy wrote that the API should spend *almost*  
all of its descriptive effort in media type and link relation  
specifications.

Since he wrote *almost* I was wondering if there was anything besides  
that.


>  I ought to
> be able to determine everything I need to know that isn't covered by
> media type or protocol definitions in-band from the hypertext.

One question: how do you *choose* the service to interact with?


Jan

Jan Algermissen wrote:
> 
> Since he wrote *almost* I was wondering if there was anything
> besides that.
> 

Yeah, I understood your question, I thought it was a good one.  But I
also thought I gave a good answer -- response codes and security
implementation.  I was simply pointing out that anything beyond
"almost" probably belongs in-line.

> 
> >  I ought to
> > be able to determine everything I need to know that isn't covered by
> > media type or protocol definitions in-band from the hypertext.
> 
> One question: how do you *choose* the service to interact with?
> 

By following a published link to some resource.  Any entry point on
your system ought to allow me to navigate to whatever resource of
interest I wish to bookmark as a future entry point.

Consider the website I'm developing now, for a local law firm.  Each
attorney has an entry on cobar.org whether they want it or not.  I
can't link from the attorneys' entries on their own domain, to their
entries on cobar.org, because cobar.org violates the identification of
resources constraint.  The only bookmarkable entry point to their
attorney-info retrieval service is at its root level.

I ought to be able to publish a link from each attorney to his or her
entry on cobar.org, and anyone following that link ought to be able to
determine the URI allocation scheme from introspecting the link, and
create their own link to some other attorney without ever consulting
documentation.  Instead, I would have to disguise a POST form as a
link, and that form could be introspected to determine the API, but
you can't bookmark a POST request.

But I digress.  It's just this pragmatic aspect of REST was thrown in
my face yesterday, when I had to explain to my client why I can't link
his page to his cobar.org profile.  He did not understand why I could
not just link to something he could navigate to, initially.  Web APIs
like cobar's put Web Developers between a rock and a hard place with
their clients, that we shouldn't have to deal with at all.  Go REST.

-Eric

On Jan 9, 2010, at 2:27 PM, Eric J. Bowman wrote:

> Jan Algermissen wrote:
>>
>> Since he wrote *almost* I was wondering if there was anything
>> besides that.
>>
>
> Yeah, I understood your question, I thought it was a good one.  But I
> also thought I gave a good answer -- response codes and security
> implementation.  I was simply pointing out that anything beyond
> "almost" probably belongs in-line.

Ah, ok. Still (as said) I think response codes are uniform (their  
meaning and when they are applicable) and security is orthogonal.

>
>>
>>> I ought to
>>> be able to determine everything I need to know that isn't covered by
>>> media type or protocol definitions in-band from the hypertext.
>>
>> One question: how do you *choose* the service to interact with?
>>
>
> By following a published link to some resource.  Any entry point on
> your system ought to allow me to navigate to whatever resource of
> interest I wish to bookmark as a future entry point.

So, there would then be a link relation that identifies the service  
type?

Would it not be simpler to use a generic service relation and let the  
client (which might as well be a crawler that wills a registry) figure  
out the service type based on what the service says about itself?

Anyhow, neither way are you getting rid of the question what makes a  
service type and how one would code a client for that service type  
*before* seeing any service instance. (Here is what I think: <http://algermissen.blogspot.com/2010/01/service-type-specifications-ii.html 
 > )

>
> Consider the website I'm developing now, for a local law firm.  Each
> attorney has an entry on cobar.org whether they want it or not.  I
> can't link from the attorneys' entries on their own domain, to their
> entries on cobar.org, because cobar.org violates the identification of
> resources constraint.  The only bookmarkable entry point to their
> attorney-info retrieval service is at its root level.

Sounds like bad design, OTH, maybe cobar.org just does not want those  
resource to be bookmarkable.

>
> I ought to be able to publish a link from each attorney to his or her
> entry on cobar.org, and anyone following that link ought to be able to
> determine the URI allocation scheme from introspecting the link, and
> create their own link to some other attorney without ever consulting
> documentation.

If cobar.org's intention was to enable that, then yes. The link  
relation specs should define the involved template parameters to  
enable URI construction from lawyer identity 'elements' (e.g.  
firstname, surname).


>  Instead, I would have to disguise a POST form as a
> link, and that form could be introspected to determine the API, but
> you can't bookmark a POST request.

You could send your clients JavaScript code that executes the  
coburg.org application in th background to get to the desired  
information (ignoring cross domain issues for the moment). For that to  
be possible there would need to be machine processable hypermedia at  
coburg.org.


>
> But I digress.  It's just this pragmatic aspect of REST was thrown in
> my face yesterday, when I had to explain to my client why I can't link
> his page to his cobar.org profile.  He did not understand why I could
> not just link to something he could navigate to, initially.  Web APIs
> like cobar's put Web Developers between a rock and a hard place with
> their clients, that we shouldn't have to deal with at all.  Go REST.


Jan


>
> -Eric
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

Hi Eric,

Particularly for amazon.com, you don't have to be logged in all the
time. Even for anonymous users, the content changes based on the
user's previous traversal thought the web site.
Some web sites have content that is region based. For example, for
www.xyz.com, different content will be shown for users from region1
and region2.
It might look bad to have explicit URLs like www.xyz.com/region1,
www.xyz.com/region2.

What will be the ' judicious use of context-setting URI' in this case?

Thanks,
Unmesh


On Sat, Jan 9, 2010 at 7:18 AM, Eric J. Bowman <eric@...> wrote:
> "unmesh_joshi" wrote:
>>
>> Many websites like amazon.com, show personalized pages using cookies.
>> This is not restful as URIs do not represent the resources, but there
>> is hidden state maintained on client side. Roy Fielding's
>> dissertation has following comment on cookie based state mechanism
>>
>> "A state mechanism that involves preferences can be more efficiently
>> implemented using judicious use of context-setting URI rather than
>> cookies, where judicious means one URI per state rather than an
>> unbounded number of URI due to the embedding of a user-id."
>>
>> Are there any examples of this? In particular, what does URI per
>> state means?
>>
>
> The state of the resource and the state of the application are not
> always the same in REST. �A personalized page is really the same
> resource state for all users, although each user's application state
> varies by username. �Instead of assigning each application state a URI
> like http://example.org/joe/welcome_page, use one URI per resource
> state, i.e. http://example.org/welcome_page, and vary its output based
> on the username present in HTTP Digest authentication headers (instead
> of cookies). �That's just one example.
>
> -Eric
>

What would one do to black box test a RESTful service?

Are there any assumptions one can make about the observable behaviour  
of a RESTful service that could be tested?

Or, rephrased, under what conditions would one claim that a RESTful  
service behaves wrongly?


Jan

Hi Jan,

For our book, Ian, Savas and I have been doing black box testing of hypermedia services. For us this means creating some tests which exercise particular workflows that a service supports (decision points are advertised through different rel values ins links).

By programming a client with some goal and rules towards reaching that goal, we can then let it loose against a service and watch as it drives towards a conclusion.

What's been nice for us (and has demonstrated the value of hypermedia for describing business protocols) has been that we wrote one set of tests per service (typically in Java) whereas for illustrative purposes the book has multiple implementations of each service (Java and .NET typically).

We've used both custom media types and common media types (especially Atom) for our services and in either case our black box tests have worked, providing both positive assertions that services work, and have uncovered bugs in our differing implementations.

Jim

Jim,

On Jan 11, 2010, at 2:01 PM, Jim Webber wrote:

> Hi Jan,
>
> For our book, Ian, Savas and I have been doing black box testing of  
> hypermedia services. For us this means creating some tests which  
> exercise particular workflows that a service supports (decision  
> points are advertised through different rel values ins links).
>
> By programming a client with some goal and rules towards reaching  
> that goal, we can then let it loose against a service and watch as  
> it drives towards a conclusion.

Are you testing whether the client can actually reach the intended goal?

>
> What's been nice for us (and has demonstrated the value of  
> hypermedia for describing business protocols) has been that we wrote  
> one set of tests per service (typically in Java) whereas for  
> illustrative purposes the book has multiple implementations of each  
> service (Java and .NET typically).
>
> We've used both custom media types and common media types  
> (especially Atom) for our services and in either case our black box  
> tests have worked, providing both positive assertions that services  
> work, and have uncovered bugs in our differing implementations.

Hmm, sorry, I think I made a mistake by saying "black box testing",  
which you (rightly) took as implementation testing.

What I intended to ask was whether a RESTful service could ever  
produce a response that could be considered 'wrong'.

Excluding server crashes and bugs like sending ill formed XML etc.

Jan

P.S. The implicit theme being 'a RESTful service can never send a  
wrong response because the client must expect to be sent anything'.

>
> Jim
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

Hi Jan,

> Are you testing whether the client can actually reach the intended goal?

Yes, which means the business protocol is tested and the implementation is tested. Just like normal functional testing really.

[snip]

> What I intended to ask was whether a RESTful service could ever produce a response that could be considered 'wrong'.

Assuming the service implementation is correct (big assumption), all the media types are properly declared (smaller assumption) and that the service won't fail for other reasons (implausible assumption!), then I agree: hypermedia corrals you towards an appropriate outcome.

> P.S. The implicit theme being 'a RESTful service can never send a wrong response because the client must expect to be sent anything'.

"anything" can only be taken in context. It will be constrained by the media types your service uses, any additional link relations you've added in, and the domain application protocol (DAP, or business protocol) that your service supports. 

Jim

Hi Jim,


On Jan 11, 2010, at 3:36 PM, Jim Webber wrote:

> Hi Jan,
>
>> Are you testing whether the client can actually reach the intended  
>> goal?
>
> Yes, which means the business protocol is tested and the  
> implementation is tested. Just like normal functional testing really.
>

What do you mean by 'business protocol'? And how do you document that  
'business protocol' (if you *test* it, I assume it is 'written down'  
somehow)?


(Sorry, please bear with me - trying to make a point)

> [snip]
>
>> What I intended to ask was whether a RESTful service could ever  
>> produce a response that could be considered 'wrong'.
>
> Assuming the service implementation is correct (big assumption), all  
> the media types are properly declared (smaller assumption) and that  
> the service won't fail for other reasons (implausible assumption!),  
> then I agree: hypermedia corrals you towards an appropriate outcome.

+1 to the assumptions and I also like the wording 'corrals you towards  
an appropriate outcome'.

>
>> P.S. The implicit theme being 'a RESTful service can never send a  
>> wrong response because the client must expect to be sent anything'.
>
> "anything" can only be taken in context. It will be constrained by  
> the media types your service uses, any additional link relations  
> you've added in, and the domain application protocol (DAP, or  
> business protocol) that your service supports.

I agree (assuming I understand you correctly)  that the perimeter  
prescribed by the hypermedia semantics (media types, rels, etc.) the  
server uses provides a context that can be used to differentiate  
between a 'valid' response and a 'nonsense' response. A 'nonsense'  
response being one that the client could not possibly have expected.

I am having trouble with the 'domain application protocol' - I think  
REST deliberately aims to avoid it to reduce coupling. OTH, I am not  
sure what you mean by 'DAP or business protocol'. Can you explain?  
Most importantly, I'd be interested in whether and how you document  
such a thing.

What I think though (and maybe that is what you mean anyway) is that a  
server cannot send an arbitrary response to any request but is bound  
to the semantics with which it linked to a given resource. For  
example, a Web server that sends HTML containing <img href="/img/foo"/ 
 > to a client must respond with an image representation when the  
client GETs /img/foo. Otherwise the server would be bogous (this is  
stuff I think is a good candidate for tests).

Web browsers (at least the ones I checked) populate the Accept header  
with image/xxx values when following the <img href=""/>. This is  
appropriate behavior because the HTML spec establishes the contract  
that <img> elements reference images. Due to the commonly known nature  
of 'an image' the spec does not really go into details what an image is.

If this line of thought is applied to resource kinds (kind as in "The  
target of <img> is an image resource") that need more detailed  
specification or carry some sort of semantic of containing references  
to other resources the situation is not that simple anymore. In my  
view, an AtomPub 'collection' is such a resource kind and there are  
certain expectations implied about the nature of the resource a  
<collection href=""> element points to. The developer of an AtomPub  
client would not populate the Accept header with image/* but rather  
application/atom+xml. However, I think that application/rss+xml or  
even text/uri-list are also possible choices because they represent  
collections.

What if this is applied to resources like orders or bug tracking  
tickets? Is there a need for media types to be 'mapped' or 'linked'  
with such resource kinds?

I think to some extend: yes. And I think that these kinds of  
'contracts' constitute a sufficient 'domain protocol' when combined  
with the knowledge about what set hypermedia semantics a service uses.

Jan






>
> Jim
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

Hey Jan,

> What do you mean by 'business protocol'? And how do you document that 'business protocol' (if you *test* it, I assume it is 'written down' somehow)?

A business protocol is a sequence of steps taken to achieve some outcome - namely the changing of state on a computer system for some useful purpose.

Protocols are written down, but in terms of media types and their associated processing models. For instance if you know application/atom+xml and the AtomPub links then you know how to process links to cause state changes on the server. Ditto for custom media types like application/vnd.restbucks+xml (a media type that covers the business

> +1 to the assumptions and I also like the wording 'corrals you towards an appropriate outcome'.

Good, that wording's in the book. Unfortunately for me I think Ian wrote it, so he can claim the credit :-)

> I agree (assuming I understand you correctly)  that the perimeter prescribed by the hypermedia semantics (media types, rels, etc.) the server uses provides a context that can be used to differentiate between a 'valid' response and a 'nonsense' response. A 'nonsense' response being one that the client could not possibly have expected.

Yup. 

> I am having trouble with the 'domain application protocol' - I think REST deliberately aims to avoid it to reduce coupling. OTH, I am not sure what you mean by 'DAP or business protocol'. Can you explain? Most importantly, I'd be interested in whether and how you document such a thing.

The domain application protocol is a business protocol that sits atop other (typically RESTful) application protocols like HTTP. It narrows the underlying protocol for a specific business case. For example, HTTP as an application protocol is very broad, but I might just want to use it to order a coffee - this narrower, more specific protocol is a DAP. Ditto if I take Atom and AtomPub and turn it into a competing consumers implementation for event-driven communication between systems narrows those formats and protocols to something more specific - a DAP in our nomenclature.

> What I think though (and maybe that is what you mean anyway) is that a server cannot send an arbitrary response to any request but is bound to the semantics with which it linked to a given resource. For example, a Web server that sends HTML containing <img href="/img/foo"/> to a client must respond with an image representation when the client GETs /img/foo. Otherwise the server would be bogous (this is stuff I think is a good candidate for tests).

Agreed. If a server returns something illegal from an interaction, then *it* has broken the contract. And contracts are binding on *both* parties.

> Web browsers (at least the ones I checked) populate the Accept header with image/xxx values when following the <img href=""/>. This is appropriate behavior because the HTML spec establishes the contract that <img> elements reference images. Due to the commonly known nature of 'an image' the spec does not really go into details what an image is.

Yes, although browsers are dead to me :-)

> If this line of thought is applied to resource kinds (kind as in "The target of <img> is an image resource") that need more detailed specification or carry some sort of semantic of containing references to other resources the situation is not that simple anymore. In my view, an AtomPub 'collection' is such a resource kind and there are certain expectations implied about the nature of the resource a <collection href=""> element points to. The developer of an AtomPub client would not populate the Accept header with image/* but rather application/atom+xml. However, I think that application/rss+xml or even text/uri-list are also possible choices because they represent collections.
> 
> What if this is applied to resources like orders or bug tracking tickets? Is there a need for media types to be 'mapped' or 'linked' with such resource kinds?

Seems a good use of Atom to me - for (time ordered) lists of stuff. Ian has written up a good example where Atom is used for a competing consumers implementation in an ecommerce scenario in our book. What's delightful about it, is that *all* the DAP stuff is done with HTTP and Atom. The code which understands what's in the Atom element is totally separate. 

> I think to some extend: yes. And I think that these kinds of 'contracts' constitute a sufficient 'domain protocol' when combined with the knowledge about what set hypermedia semantics a service uses.

Great. But now I think I've taken us off track from our original testing question, sorry!

Jim

Jim,

On Jan 11, 2010, at 9:28 PM, Jim Webber wrote:

> Great. But now I think I've taken us off track from our original  
> testing question, sorry!

Not really. My intention was to approach the 'coupling theme' from a  
different angle by focussing on what is testable. Something that makes  
sense to be tested contributes to the contract between client and  
server and constitutes coupling.


Jan

> Not really. My intention was to approach the 'coupling theme' from a  
> different angle by focussing on what is testable. Something that makes  
> sense to be tested contributes to the contract between client and  
> server and constitutes coupling.

Ah, fair point. I get it now.

Jim

You should instead focus on why defining media type(s) used for representing resources is the most important design activity.  If you have some steps left over, then it will be obvious what it doesn't cover.

For what it's worth, this is exactly why the Amazon programming language APIs, such as the C# S3 API, are very non-RESTful.  Even the third party APIs incur epic failure when subject to this basic eyeball test.

Actually, Amazon's API documentation for programming languages is also inconsistent in how it wraps HTTP, from language to language.  The sample C# code is simply wrong and broken, stupid and ugly.  It doesn't even pass through the FxCop/StyleCop rules gauntlet.  Whoever wrote it was hopefully an intern, because I'd hate to think Amazon hires developers to write "REST APIs" without having any clue how to even program correctly, much less understand REST...

--- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
>
> 
> In [1] Roy writes
> 
> "A REST API should spend almost all of its descriptive effort in  
> defining the media type(s) used for representing resources and driving  
> application state, or in defining extended relation names and/or  
> hypertext-enabled mark-up for existing standard media types. [...]"
> 
> Maybe I am reading too much into this, but then...usually Roy chooses  
> his words quite carefully:
> 
> Does anyone know why it is "*almost* all of its descriptive effort"  
> and not simply "all of its descriptive effort"? What else is there to  
> be described than the media types?
> 
> Jan
> 
> 
> [1] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
>

> 
> Particularly for amazon.com, you don't have to be logged in all the
> time. Even for anonymous users, the content changes based on the
> user's previous traversal thought the web site.
>

If you aren't logged in, the server can just send the anonymous
representation.  The server isn't required to initiate challenge-
response.  We just discussed this here:

http://tech.groups.yahoo.com/group/rest-discuss/message/14399

As to tracking anonymous users who aren't logged in, well, that is a
job for cookies AFAIK.

>
> Some web sites have content that is region based. For example, for
> www.xyz.com, different content will be shown for users from region1
> and region2.
> It might look bad to have explicit URLs like www.xyz.com/region1,
> www.xyz.com/region2.
> 
> What will be the ' judicious use of context-setting URI' in this case?
> 

Good question.  I'm pretty busy today, so I'm going to punt...

-Eric

>>>>> "Eric" == Eric J Bowman <eric@...> writes:

    Eric> As to tracking anonymous users who aren't logged in, well,
    Eric> that is a job for cookies AFAIK.

The techniques that have been proposed here, and are in use by people,
are:

1. Always login someone, so create a dummy account as soon as a new
   user logs in. You can accept any or the dummy password in that case
   and with JavaScript you can log them in automatically.

2. And of course url with a unique id in it.


Of course, both techniques have issues with session restart.


But with HTML5 we have local storage, which will work as well as
cookies, so we can do away with them entirely. I.e. I would use
technique 1 with local storage to keep track with the dummy user id.

-- 
Cheers,

Berend de Boer

ok,

I can use link "rel" to offer the client a list of possible next states ....

question: doing tat I expect the client to know what is the semantic
of each link, isn't it ?

If yes, hateoas seems not feasible since the client needs a previous
knowledge about what to look for in the list of links... (unless there
is only one link, of course)

the question is: can I create my own relation semantics ? or should I
grasp in the available ones for Atom and Xhtml in case I want to
produce HATEOAS systems?

* I am trying to implement HATEOAS using Jersey.. I know it has no
support out of the box, so I am designing some tricks here :)

regards,


    Felipe Ga�cho

Hi Felipe,

[snip]

> question: doing tat I expect the client to know what is the semantic
> of each link, isn't it ?

Yes, that's right. The client should understand the rel value within the context of the representation it's found in. This may come from a media type, maybe a protocol, or a registry of link relations. But the client does need to know about them.

> If yes, hateoas seems not feasible since the client needs a previous
> knowledge about what to look for in the list of links... (unless there
> is only one link, of course)

I'd disagree here. HATEAOS is still quite feasible, but the client needs to know the processing model for the media types it's dealing with - they're a key part of a service's contract.

> the question is: can I create my own relation semantics ? or should I
> grasp in the available ones for Atom and Xhtml in case I want to
> produce HATEOAS systems?

You can create your own semantics; you can create your own media types too. The trade off is one of reach (that is, reusing existing software out there on the Web) versus applicability (you can craft something that matches your domain exactly).

FWIW I generally prefer to try to solve problems with existing media types before resorting to custom media types.

> * I am trying to implement HATEOAS using Jersey.. I know it has no
> support out of the box, so I am designing some tricks here :)

Shameless plug: Chapter 5 of the book Ian, Savas, and I are writing actually has examples of a hypermedia system written with Jersey.

Jim

Felipe,

On Jan 13, 2010, at 3:49 PM, Felipe Ga�cho wrote:

> ok,
>
> I can use link "rel" to offer the client a list of possible next  
> states ....
>
> question: doing tat I expect the client to know what is the semantic
> of each link, isn't it ?

Yes. HTML browsers do this everyday (images, stylesheets,..).

>
> If yes, hateoas seems not feasible since the client needs a previous
> knowledge about what to look for in the list of links... (unless there
> is only one link, of course)

When the client receives text/html and sees an <img href=""/> it does  
make an assumption about the nature of the target resource. In this  
case, that it is an image. The set of formats the client puts in the  
Accept header when requesting the image representation (GET) is driven  
by built-in knowledge which media types the client understands are  
media types for images.

This gets a bit more interesting when the nature of the link target  
implies that there are other links. When an AtomPub service document  
contains <collection href="/cols/1"> the client makes the assumption  
(based on RFC5023) that /cols/1 is a collection. The semantic of  
'collection' includes the notion of having a (possibly empty) set of  
members. While the client should not make any assumptions about the  
exact media type the server will send for a GET to the collection, the  
client does make the assumption that whatever representation it  
receives 'matches' the collection nature.

The essential question (for me anyway) is, on what basis the client  
populates the Accept header when GETing /cols/1. RFC5023 sort of  
mandates the server to return an Atom feed, but from a REST POV (as  
Roy rightly pointed out[1]) this is overly constraining. Have a look  
at OpenSearch; nothing in the OpenSearch set of specs tells the client  
developer what media types will be used for search results (which are  
essentially sets of links with metadata). But from reading the  
documentation a client developer learns that Atom feeds and RSS feeds  
are commonly used.

Client and server not only need to understand the media types used for  
communication, but they must share an understanding of what media  
types are used or can be expected to be used for which kinds of  
resources ('kind of resource' being implied by hypermedia semantics).

(I have agonized this list with this subject over the last weeks, so  
you might want to check those archives. The same on atom-protocol: [2])


>
> the question is: can I create my own relation semantics ? or should I
> grasp in the available ones for Atom and Xhtml in case I want to
> produce HATEOAS systems?

Oops - seems like you did not ask what I thought you were asking. Sorry.

Yes, you create your own hypermdia semantics by defining media types  
(or defining extensions for existing ones) or 'stand-alone' link  
relations. The more you can re-use existing ones the better, but often  
these are just too unspecific. Before risking to accidentally baking  
out-of-band knowledge into your clients and servers I'd roll my own  
hypermedia.

>
> * I am trying to implement HATEOAS using Jersey.. I know it has no
> support out of the box, so I am designing some tricks here :)

Are you in a pure machine to machine scenario or is the client  
application controlled by a human user?

Jan


>

[1] http://www.imc.org/atom-protocol/mail-archive/msg11487.html
[2] http://www.imc.org/atom-protocol/mail-archive/msg11463.html


> regards,
>
>
>    Felipe Ga�cho
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

Hello Felipe,


> > If yes, hateoas seems not feasible since the client needs a previous
> > knowledge about what to look for in the list of links... (unless there
> > is only one link, of course)
>

If content negotiation is taking place, all responses are understood by your
client application, otherwise a response code indicating that there is no
media type available for answering the request would be the proper response.
If your server stick with well known media types, most clients will have no
problem understanding responses. If it goes for its own custom one, the
intimacy between both parts might be higher than it should.

As Jim pointed, try to use a well known one. If you can not, use your own.

Regards

My current approach is to use existing media types (to take advantage
of their existing semantics) and add "rel" values as needed.

I start by using the values already registered and available [1,2] and
supplement those with ones I create to meet the domain-specific need.
When I create my own, I use a rel value that is a resolve-able URI and
place helpful documentation at that URI. I'ved used the following two
formats in the past:

rel="http://www.example.org/rels/cancel-order"
rel="http://www.example.org/rels/purchasing#cancel-order"

In the second example, a single document is available that lists
several related rel values. It's a documentation optimization only.

[1] http://www.iana.org/assignments/link-relations/link-relations.xhtml
[2] http://dublincore.org/documents/dces/

mca
http://amundsen.com/blog/




2010/1/13 Felipe Ga�cho <fgaucho@...>:
> ok,
>
> I can use link "rel" to offer the client a list of possible next states ....
>
> question: doing tat I expect the client to know what is the semantic
> of each link, isn't it ?
>
> If yes, hateoas seems not feasible since the client needs a previous
> knowledge about what to look for in the list of links... (unless there
> is only one link, of course)
>
> the question is: can I create my own relation semantics ? or should I
> grasp in the available ones for Atom and Xhtml in case I want to
> produce HATEOAS systems?
>
> * I am trying to implement HATEOAS using Jersey.. I know it has no
> support out of the box, so I am designing some tricks here :)
>
> regards,
>
>
> � �Felipe Ga�cho
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

Hi amundsen,

you are using the relation  attribute for the navigation.. strange..

relation should just give the client a hint about the relation between
a resource and the url in the link element.. not a URI itself..

imho..

I got the point about the original question, thanks a lot for all responses.


   Felipe Ga�cho.

2010/1/13 mike amundsen <mamund@...>:
> My current approach is to use existing media types (to take advantage
> of their existing semantics) and add "rel" values as needed.
>
> I start by using the values already registered and available [1,2] and
> supplement those with ones I create to meet the domain-specific need.
> When I create my own, I use a rel value that is a resolve-able URI and
> place helpful documentation at that URI. I'ved used the following two
> formats in the past:
>
> rel="http://www.example.org/rels/cancel-order"
> rel="http://www.example.org/rels/purchasing#cancel-order"
>
> In the second example, a single document is available that lists
> several related rel values. It's a documentation optimization only.
>
> [1] http://www.iana.org/assignments/link-relations/link-relations.xhtml
> [2] http://dublincore.org/documents/dces/
>
> mca
> http://amundsen.com/blog/
>
>
>
>
> 2010/1/13 Felipe Ga�cho <fgaucho@...>:
>> ok,
>>
>> I can use link "rel" to offer the client a list of possible next states ....
>>
>> question: doing tat I expect the client to know what is the semantic
>> of each link, isn't it ?
>>
>> If yes, hateoas seems not feasible since the client needs a previous
>> knowledge about what to look for in the list of links... (unless there
>> is only one link, of course)
>>
>> the question is: can I create my own relation semantics ? or should I
>> grasp in the available ones for Atom and Xhtml in case I want to
>> produce HATEOAS systems?
>>
>> * I am trying to implement HATEOAS using Jersey.. I know it has no
>> support out of the box, so I am designing some tricks here :)
>>
>> regards,
>>
>>
>> � �Felipe Ga�cho
>>
>>
>> ------------------------------------
>>
>> Yahoo! Groups Links
>>
>>
>>
>>
>



-- 
------------------------------------------
   Felipe Ga�cho
   10+ Java Programmer
   CEJUG Senior Advisor

On Jan 13, 2010, at 4:52 PM, Felipe Ga�cho wrote:

> Hi amundsen,
>
> you are using the relation  attribute for the navigation.. strange..

No, the URI identifies the extension relation. Google for Link header  
draft.

Jan

>
> relation should just give the client a hint about the relation between
> a resource and the url in the link element.. not a URI itself..
>
> imho..
>
> I got the point about the original question, thanks a lot for all  
> responses.
>
>
>   Felipe Ga�cho.
>
> 2010/1/13 mike amundsen <mamund@...>:
>> My current approach is to use existing media types (to take advantage
>> of their existing semantics) and add "rel" values as needed.
>>
>> I start by using the values already registered and available [1,2]  
>> and
>> supplement those with ones I create to meet the domain-specific need.
>> When I create my own, I use a rel value that is a resolve-able URI  
>> and
>> place helpful documentation at that URI. I'ved used the following two
>> formats in the past:
>>
>> rel="http://www.example.org/rels/cancel-order"
>> rel="http://www.example.org/rels/purchasing#cancel-order"
>>
>> In the second example, a single document is available that lists
>> several related rel values. It's a documentation optimization only.
>>
>> [1] http://www.iana.org/assignments/link-relations/link-relations.xhtml
>> [2] http://dublincore.org/documents/dces/
>>
>> mca
>> http://amundsen.com/blog/
>>
>>
>>
>>
>> 2010/1/13 Felipe Ga�cho <fgaucho@...>:
>>> ok,
>>>
>>> I can use link "rel" to offer the client a list of possible next  
>>> states ....
>>>
>>> question: doing tat I expect the client to know what is the semantic
>>> of each link, isn't it ?
>>>
>>> If yes, hateoas seems not feasible since the client needs a previous
>>> knowledge about what to look for in the list of links... (unless  
>>> there
>>> is only one link, of course)
>>>
>>> the question is: can I create my own relation semantics ? or  
>>> should I
>>> grasp in the available ones for Atom and Xhtml in case I want to
>>> produce HATEOAS systems?
>>>
>>> * I am trying to implement HATEOAS using Jersey.. I know it has no
>>> support out of the box, so I am designing some tricks here :)
>>>
>>> regards,
>>>
>>>
>>>    Felipe Ga�cho
>>>
>>>
>>> ------------------------------------
>>>
>>> Yahoo! Groups Links
>>>
>>>
>>>
>>>
>>
>
>
>
> -- 
> ------------------------------------------
>   Felipe Ga�cho
>   10+ Java Programmer
>   CEJUG Senior Advisor
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

Mike,

On Jan 13, 2010, at 4:49 PM, mike amundsen wrote:

> My current approach is to use existing media types (to take advantage
> of their existing semantics) and add "rel" values as needed.
>
> I start by using the values already registered and available [1,2] and
> supplement those with ones I create to meet the domain-specific need.
> When I create my own, I use a rel value that is a resolve-able URI and
> place helpful documentation at that URI. I'ved used the following two
> formats in the past:
>
> rel="http://www.example.org/rels/cancel-order"
> rel="http://www.example.org/rels/purchasing#cancel-order"

Just a comment:

For such cases I'd actually avoid the introduction of a link semantic  
and use DELETE because the client would presumably already know it is  
dealing with an order resource:

DELETE /orders/6

As a rule of thumb I do this:

When the domain operation in question ('cancel an order') maps o the  
base semantics of an existing HTTP method use that method to gain the  
visibility advantages over using the generic POST. In the example,  
caching would (in theory) benefit from the visibility of DELETE (as  
opposed to POST) by knowing that all caches of that order resource  
could be flushed.

Jan


>
> In the second example, a single document is available that lists
> several related rel values. It's a documentation optimization only.
>
> [1] http://www.iana.org/assignments/link-relations/link- 
> relations.xhtml
> [2] http://dublincore.org/documents/dces/
>
> mca
> http://amundsen.com/blog/
>
>
>
>
> 2010/1/13 Felipe Ga�cho <fgaucho@...>:
>> ok,
>>
>> I can use link "rel" to offer the client a list of possible next  
>> states ....
>>
>> question: doing tat I expect the client to know what is the semantic
>> of each link, isn't it ?
>>
>> If yes, hateoas seems not feasible since the client needs a previous
>> knowledge about what to look for in the list of links... (unless  
>> there
>> is only one link, of course)
>>
>> the question is: can I create my own relation semantics ? or should I
>> grasp in the available ones for Atom and Xhtml in case I want to
>> produce HATEOAS systems?
>>
>> * I am trying to implement HATEOAS using Jersey.. I know it has no
>> support out of the box, so I am designing some tricks here :)
>>
>> regards,
>>
>>
>>    Felipe Ga�cho
>>
>>
>> ------------------------------------
>>
>> Yahoo! Groups Links
>>
>>
>>
>>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

> FWIW I generally prefer to try to solve problems with existing media types
> before resorting to custom media types.
>

Why would this make a difference?  We keep talking about reach, but most (if
not all?) media types were designed for a specific client.  If not
developing an application that is not  'type' of that original client (say a
feed aggregator), I can't see how the existing media types (outside of
possible html) would not require some extensions to it (as alluded too by
Mike in his examples).  Why is this extension better than rolling out a new
media type if in both cases, "additional" information needs to be
documented?  What are the practical reasons?  When would a custom media type
make sense?

Thanks.

Eb

>
>
> For such cases I'd actually avoid the introduction of a link semantic
> and use DELETE because the client would presumably already know it is
> dealing with an order resource:
>
+1, but I think Mike just wrote the example to show how one could use it.

Jan, about the Link header, I wanted to ask earlier in another discussion
but found it too offtopic. I can't see how I can use it (instead of atom
links) to represent multiple links within a collection. For example, if I
have a collection of cities and each city has its own URI, how could the
Link header in a no-nasty way represent a "self" relation to each city?

The city representations are in the content body, but the resource being
presented is the set of cities. The header is related to the set, but how to
relate them to each item?

I am probably missing something.

Regards



>
> DELETE /orders/6
>
> As a rule of thumb I do this:
>
> When the domain operation in question ('cancel an order') maps o the
> base semantics of an existing HTTP method use that method to gain the
> visibility advantages over using the generic POST. In the example,
> caching would (in theory) benefit from the visibility of DELETE (as
> opposed to POST) by knowing that all caches of that order resource
> could be flushed.
>
> Jan
>
>
> >
> > In the second example, a single document is available that lists
> > several related rel values. It's a documentation optimization only.
> >
> > [1] http://www.iana.org/assignments/link-relations/link-
> > relations.xhtml
> > [2] http://dublincore.org/documents/dces/
> >
> > mca
> > http://amundsen.com/blog/
> >
> >
> >
> >
> > 2010/1/13 Felipe Ga�cho <fgaucho@... <fgaucho%40gmail.com>>:
> >> ok,
> >>
> >> I can use link "rel" to offer the client a list of possible next
> >> states ....
> >>
> >> question: doing tat I expect the client to know what is the semantic
> >> of each link, isn't it ?
> >>
> >> If yes, hateoas seems not feasible since the client needs a previous
> >> knowledge about what to look for in the list of links... (unless
> >> there
> >> is only one link, of course)
> >>
> >> the question is: can I create my own relation semantics ? or should I
> >> grasp in the available ones for Atom and Xhtml in case I want to
> >> produce HATEOAS systems?
> >>
> >> * I am trying to implement HATEOAS using Jersey.. I know it has no
> >> support out of the box, so I am designing some tricks here :)
> >>
> >> regards,
> >>
> >>
> >> Felipe Ga�cho
> >>
> >>
> >> ------------------------------------
> >>
> >> Yahoo! Groups Links
> >>
> >>
> >>
> >>
> >
> >
> > ------------------------------------
> >
> > Yahoo! Groups Links
> >
> >
> >
>
> --------------------------------------
> Jan Algermissen
>
> Mail: algermissen@... <algermissen%40acm.org>
> Blog: http://algermissen.blogspot.com/
> Home: http://www.jalgermissen.com
> --------------------------------------
>
>  
>

Jan:

<snip>
For such cases I'd actually avoid the introduction of a link semantic and
use DELETE because the client would presumably already know it is dealing
with an order resource:
</snip>

In the case i gave, the rel value documentation instructs developers
to use the DELETE method when activating the associated URI unless
they are working with an agent that does not support the DELETE method
(Web browsers) in which case the  POST method is an acceptable
alternative.

mca
http://amundsen.com/blog/




On Wed, Jan 13, 2010 at 11:02, Jan Algermissen <algermissen1971@...> wrote:
> Mike,
>
> On Jan 13, 2010, at 4:49 PM, mike amundsen wrote:
>
>> My current approach is to use existing media types (to take advantage
>> of their existing semantics) and add "rel" values as needed.
>>
>> I start by using the values already registered and available [1,2] and
>> supplement those with ones I create to meet the domain-specific need.
>> When I create my own, I use a rel value that is a resolve-able URI and
>> place helpful documentation at that URI. I'ved used the following two
>> formats in the past:
>>
>> rel="http://www.example.org/rels/cancel-order"
>> rel="http://www.example.org/rels/purchasing#cancel-order"
>
> Just a comment:
>
> For such cases I'd actually avoid the introduction of a link semantic and
> use DELETE because the client would presumably already know it is dealing
> with an order resource:
>
> DELETE /orders/6
>
> As a rule of thumb I do this:
>
> When the domain operation in question ('cancel an order') maps o the base
> semantics of an existing HTTP method use that method to gain the visibility
> advantages over using the generic POST. In the example, caching would (in
> theory) benefit from the visibility of DELETE (as opposed to POST) by
> knowing that all caches of that order resource could be flushed.
>
> Jan
>
>
>>
>> In the second example, a single document is available that lists
>> several related rel values. It's a documentation optimization only.
>>
>> [1] http://www.iana.org/assignments/link-relations/link-relations.xhtml
>> [2] http://dublincore.org/documents/dces/
>>
>> mca
>> http://amundsen.com/blog/
>>
>>
>>
>>
>> 2010/1/13 Felipe Ga�cho <fgaucho@...>:
>>>
>>> ok,
>>>
>>> I can use link "rel" to offer the client a list of possible next states
>>> ....
>>>
>>> question: doing tat I expect the client to know what is the semantic
>>> of each link, isn't it ?
>>>
>>> If yes, hateoas seems not feasible since the client needs a previous
>>> knowledge about what to look for in the list of links... (unless there
>>> is only one link, of course)
>>>
>>> the question is: can I create my own relation semantics ? or should I
>>> grasp in the available ones for Atom and Xhtml in case I want to
>>> produce HATEOAS systems?
>>>
>>> * I am trying to implement HATEOAS using Jersey.. I know it has no
>>> support out of the box, so I am designing some tricks here :)
>>>
>>> regards,
>>>
>>>
>>> � Felipe Ga�cho
>>>
>>>
>>> ------------------------------------
>>>
>>> Yahoo! Groups Links
>>>
>>>
>>>
>>>
>>
>>
>> ------------------------------------
>>
>> Yahoo! Groups Links
>>
>>
>>
>
> --------------------------------------
> Jan Algermissen
>
> Mail: algermissen@...
> Blog: http://algermissen.blogspot.com/
> Home: http://www.jalgermissen.com
> --------------------------------------
>
>
>
>

On Jan 13, 2010, at 5:06 PM, Eb wrote:

>
>
>
> FWIW I generally prefer to try to solve problems with existing media  
> types before resorting to custom media types.
>
> Why would this make a difference?  We keep talking about reach, but  
> most (if not all?) media types were designed for a specific client.   
> If not developing an application that is not  'type' of that  
> original client (say a feed aggregator), I can't see how the  
> existing media types (outside of possible html) would not require  
> some extensions to it (as alluded too by Mike in his examples).  Why  
> is this extension better than rolling out a new media type if in  
> both cases, "additional" information needs to be documented?  What  
> are the practical reasons?  When would a custom media type make sense?
>

It is a trade off. You are correctly saying that either way, you need  
additional semantics. Using existing types with extensions makes it  
possible to use existing tools. For example, for debugging. It is a  
huge benefit if you can view your HTML+microformats orders in a  
browser to see what is going on or to subscribe to the collection of  
latest orders with a feed reader. However, managing extensions is  
somewhat difficult because you are constantly dealing with a set of  
independent stuff that constitutes some contract but yet has no name.

I like using a profile notion for this kind of 'media type  
subclassing'. The profile URI provides a nice 'handle' for the  
semantics established by the set of extensions. You can use a profile  
for conneg like this

Accept: text/html;profile="http://foo-company.org/profiles/simple-order-uf-profile

to tell the server that the client expects a certain 'kind of html'.

Jan



> Thanks.
>
> Eb
>
>
>
> 

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

On Jan 13, 2010, at 5:06 PM, Guilherme Silveira wrote:

>
> For such cases I'd actually avoid the introduction of a link semantic
> and use DELETE because the client would presumably already know it is
> dealing with an order resource:
> +1, but I think Mike just wrote the example to show how one could  
> use it.

yes, just wanted to add that.

>
> Jan, about the Link header, I wanted to ask earlier in another  
> discussion but found it too offtopic. I can't see how I can use it  
> (instead of atom links) to represent multiple links within a  
> collection. For example, if I have a collection of cities and each  
> city has its own URI, how could the Link header in a no-nasty way  
> represent a "self" relation to each city?

It can't. The Link header applies to the requested resource.

>
> The city representations are in the content body, but the resource  
> being presented is the set of cities. The header is related to the  
> set, but how to relate them to each item?

Use <atom:link>s instead.

>
> I am probably missing something.

Jan


>
> Regards
>
>
>
> DELETE /orders/6
>
> As a rule of thumb I do this:
>
> When the domain operation in question ('cancel an order') maps o the
> base semantics of an existing HTTP method use that method to gain the
> visibility advantages over using the generic POST. In the example,
> caching would (in theory) benefit from the visibility of DELETE (as
> opposed to POST) by knowing that all caches of that order resource
> could be flushed.
>
> Jan
>
>
> >
> > In the second example, a single document is available that lists
> > several related rel values. It's a documentation optimization only.
> >
> > [1] http://www.iana.org/assignments/link-relations/link-
> > relations.xhtml
> > [2] http://dublincore.org/documents/dces/
> >
> > mca
> > http://amundsen.com/blog/
> >
> >
> >
> >
> > 2010/1/13 Felipe Ga�cho <fgaucho@...>:
> >> ok,
> >>
> >> I can use link "rel" to offer the client a list of possible next
> >> states ....
> >>
> >> question: doing tat I expect the client to know what is the  
> semantic
> >> of each link, isn't it ?
> >>
> >> If yes, hateoas seems not feasible since the client needs a  
> previous
> >> knowledge about what to look for in the list of links... (unless
> >> there
> >> is only one link, of course)
> >>
> >> the question is: can I create my own relation semantics ? or  
> should I
> >> grasp in the available ones for Atom and Xhtml in case I want to
> >> produce HATEOAS systems?
> >>
> >> * I am trying to implement HATEOAS using Jersey.. I know it has no
> >> support out of the box, so I am designing some tricks here :)
> >>
> >> regards,
> >>
> >>
> >> Felipe Ga�cho
> >>
> >>
> >> ------------------------------------
> >>
> >> Yahoo! Groups Links
> >>
> >>
> >>
> >>
> >
> >
> > ------------------------------------
> >
> > Yahoo! Groups Links
> >
> >
> >
>
> --------------------------------------
> Jan Algermissen
>
> Mail: algermissen@...
> Blog: http://algermissen.blogspot.com/
> Home: http://www.jalgermissen.com
> --------------------------------------
>
>
> 
>

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

On Jan 13, 2010, at 5:11 PM, mike amundsen wrote:

> Jan:
>
> <snip>
> For such cases I'd actually avoid the introduction of a link  
> semantic and
> use DELETE because the client would presumably already know it is  
> dealing
> with an order resource:
> </snip>
>
> In the case i gave, the rel value documentation instructs developers
> to use the DELETE method when activating the associated URI unless
> they are working with an agent that does not support the DELETE method
> (Web browsers) in which case the  POST method is an acceptable
> alternative.

Is that a production use case? Can you share the complete hypermedia?

Jan


>
> mca
> http://amundsen.com/blog/
>
>
>
>
> On Wed, Jan 13, 2010 at 11:02, Jan Algermissen <algermissen1971@mac.com 
> > wrote:
>> Mike,
>>
>> On Jan 13, 2010, at 4:49 PM, mike amundsen wrote:
>>
>>> My current approach is to use existing media types (to take  
>>> advantage
>>> of their existing semantics) and add "rel" values as needed.
>>>
>>> I start by using the values already registered and available [1,2]  
>>> and
>>> supplement those with ones I create to meet the domain-specific  
>>> need.
>>> When I create my own, I use a rel value that is a resolve-able URI  
>>> and
>>> place helpful documentation at that URI. I'ved used the following  
>>> two
>>> formats in the past:
>>>
>>> rel="http://www.example.org/rels/cancel-order"
>>> rel="http://www.example.org/rels/purchasing#cancel-order"
>>
>> Just a comment:
>>
>> For such cases I'd actually avoid the introduction of a link  
>> semantic and
>> use DELETE because the client would presumably already know it is  
>> dealing
>> with an order resource:
>>
>> DELETE /orders/6
>>
>> As a rule of thumb I do this:
>>
>> When the domain operation in question ('cancel an order') maps o  
>> the base
>> semantics of an existing HTTP method use that method to gain the  
>> visibility
>> advantages over using the generic POST. In the example, caching  
>> would (in
>> theory) benefit from the visibility of DELETE (as opposed to POST) by
>> knowing that all caches of that order resource could be flushed.
>>
>> Jan
>>
>>
>>>
>>> In the second example, a single document is available that lists
>>> several related rel values. It's a documentation optimization only.
>>>
>>> [1] http://www.iana.org/assignments/link-relations/link-relations.xhtml
>>> [2] http://dublincore.org/documents/dces/
>>>
>>> mca
>>> http://amundsen.com/blog/
>>>
>>>
>>>
>>>
>>> 2010/1/13 Felipe Ga�cho <fgaucho@...>:
>>>>
>>>> ok,
>>>>
>>>> I can use link "rel" to offer the client a list of possible next  
>>>> states
>>>> ....
>>>>
>>>> question: doing tat I expect the client to know what is the  
>>>> semantic
>>>> of each link, isn't it ?
>>>>
>>>> If yes, hateoas seems not feasible since the client needs a  
>>>> previous
>>>> knowledge about what to look for in the list of links... (unless  
>>>> there
>>>> is only one link, of course)
>>>>
>>>> the question is: can I create my own relation semantics ? or  
>>>> should I
>>>> grasp in the available ones for Atom and Xhtml in case I want to
>>>> produce HATEOAS systems?
>>>>
>>>> * I am trying to implement HATEOAS using Jersey.. I know it has no
>>>> support out of the box, so I am designing some tricks here :)
>>>>
>>>> regards,
>>>>
>>>>
>>>>   Felipe Ga�cho
>>>>
>>>>
>>>> ------------------------------------
>>>>
>>>> Yahoo! Groups Links
>>>>
>>>>
>>>>
>>>>
>>>
>>>
>>> ------------------------------------
>>>
>>> Yahoo! Groups Links
>>>
>>>
>>>
>>
>> --------------------------------------
>> Jan Algermissen
>>
>> Mail: algermissen@...
>> Blog: http://algermissen.blogspot.com/
>> Home: http://www.jalgermissen.com
>> --------------------------------------
>>
>>
>>
>>

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

Jan:

<snip>
Accept: text/html;profile="http://foo-company.org/profiles/simple-order-uf-profile
</snip>

interesting...

i've been working on a case right now that uses XHTML and was
considering using HTML Profiles [1] to mark the HEAD of the document
w/ a set of "pre-conditions" that the client would scan to make sure
they can "understand" the contents of the document. Still playing with
this idea, but it sounds like it might be similar.

[1] http://www.w3.org/TR/html401/struct/global.html#profiles

mca
http://amundsen.com/blog/




On Wed, Jan 13, 2010 at 11:17, Jan Algermissen <algermissen1971@...> wrote:
>
> On Jan 13, 2010, at 5:06 PM, Eb wrote:
>
>>
>>
>>
>> FWIW I generally prefer to try to solve problems with existing media
>> types before resorting to custom media types.
>>
>> Why would this make a difference? �We keep talking about reach, but
>> most (if not all?) media types were designed for a specific client.
>> If not developing an application that is not �'type' of that
>> original client (say a feed aggregator), I can't see how the
>> existing media types (outside of possible html) would not require
>> some extensions to it (as alluded too by Mike in his examples). �Why
>> is this extension better than rolling out a new media type if in
>> both cases, "additional" information needs to be documented? �What
>> are the practical reasons? �When would a custom media type make sense?
>>
>
> It is a trade off. You are correctly saying that either way, you need
> additional semantics. Using existing types with extensions makes it
> possible to use existing tools. For example, for debugging. It is a
> huge benefit if you can view your HTML+microformats orders in a
> browser to see what is going on or to subscribe to the collection of
> latest orders with a feed reader. However, managing extensions is
> somewhat difficult because you are constantly dealing with a set of
> independent stuff that constitutes some contract but yet has no name.
>
> I like using a profile notion for this kind of 'media type
> subclassing'. The profile URI provides a nice 'handle' for the
> semantics established by the set of extensions. You can use a profile
> for conneg like this
>
> Accept: text/html;profile="http://foo-company.org/profiles/simple-order-uf-profile
>
> to tell the server that the client expects a certain 'kind of html'.
>
> Jan
>
>
>
>> Thanks.
>>
>> Eb
>>
>>
>>
>>
>
> --------------------------------------
> Jan Algermissen
>
> Mail: algermissen@...
> Blog: http://algermissen.blogspot.com/
> Home: http://www.jalgermissen.com
> --------------------------------------
>
>
>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

Jan:

<snip>
Is that a production use case? Can you share the complete hypermedia?
</snip>

the example i have in mind is behind a firewall. if you're interested,
i can proly work up a quick sample to public view.

mca
http://amundsen.com/blog/




On Wed, Jan 13, 2010 at 11:23, Jan Algermissen <algermissen1971@...> wrote:
>
> On Jan 13, 2010, at 5:11 PM, mike amundsen wrote:
>
>> Jan:
>>
>> <snip>
>> For such cases I'd actually avoid the introduction of a link semantic and
>> use DELETE because the client would presumably already know it is dealing
>> with an order resource:
>> </snip>
>>
>> In the case i gave, the rel value documentation instructs developers
>> to use the DELETE method when activating the associated URI unless
>> they are working with an agent that does not support the DELETE method
>> (Web browsers) in which case the �POST method is an acceptable
>> alternative.
>
> Is that a production use case? Can you share the complete hypermedia?
>
> Jan
>
>
>>
>> mca
>> http://amundsen.com/blog/
>>
>>
>>
>>
>> On Wed, Jan 13, 2010 at 11:02, Jan Algermissen <algermissen1971@...>
>> wrote:
>>>
>>> Mike,
>>>
>>> On Jan 13, 2010, at 4:49 PM, mike amundsen wrote:
>>>
>>>> My current approach is to use existing media types (to take advantage
>>>> of their existing semantics) and add "rel" values as needed.
>>>>
>>>> I start by using the values already registered and available [1,2] and
>>>> supplement those with ones I create to meet the domain-specific need.
>>>> When I create my own, I use a rel value that is a resolve-able URI and
>>>> place helpful documentation at that URI. I'ved used the following two
>>>> formats in the past:
>>>>
>>>> rel="http://www.example.org/rels/cancel-order"
>>>> rel="http://www.example.org/rels/purchasing#cancel-order"
>>>
>>> Just a comment:
>>>
>>> For such cases I'd actually avoid the introduction of a link semantic and
>>> use DELETE because the client would presumably already know it is dealing
>>> with an order resource:
>>>
>>> DELETE /orders/6
>>>
>>> As a rule of thumb I do this:
>>>
>>> When the domain operation in question ('cancel an order') maps o the base
>>> semantics of an existing HTTP method use that method to gain the
>>> visibility
>>> advantages over using the generic POST. In the example, caching would (in
>>> theory) benefit from the visibility of DELETE (as opposed to POST) by
>>> knowing that all caches of that order resource could be flushed.
>>>
>>> Jan
>>>
>>>
>>>>
>>>> In the second example, a single document is available that lists
>>>> several related rel values. It's a documentation optimization only.
>>>>
>>>> [1] http://www.iana.org/assignments/link-relations/link-relations.xhtml
>>>> [2] http://dublincore.org/documents/dces/
>>>>
>>>> mca
>>>> http://amundsen.com/blog/
>>>>
>>>>
>>>>
>>>>
>>>> 2010/1/13 Felipe Ga�cho <fgaucho@...>:
>>>>>
>>>>> ok,
>>>>>
>>>>> I can use link "rel" to offer the client a list of possible next states
>>>>> ....
>>>>>
>>>>> question: doing tat I expect the client to know what is the semantic
>>>>> of each link, isn't it ?
>>>>>
>>>>> If yes, hateoas seems not feasible since the client needs a previous
>>>>> knowledge about what to look for in the list of links... (unless there
>>>>> is only one link, of course)
>>>>>
>>>>> the question is: can I create my own relation semantics ? or should I
>>>>> grasp in the available ones for Atom and Xhtml in case I want to
>>>>> produce HATEOAS systems?
>>>>>
>>>>> * I am trying to implement HATEOAS using Jersey.. I know it has no
>>>>> support out of the box, so I am designing some tricks here :)
>>>>>
>>>>> regards,
>>>>>
>>>>>
>>>>> �Felipe Ga�cho
>>>>>
>>>>>
>>>>> ------------------------------------
>>>>>
>>>>> Yahoo! Groups Links
>>>>>
>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>>> ------------------------------------
>>>>
>>>> Yahoo! Groups Links
>>>>
>>>>
>>>>
>>>
>>> --------------------------------------
>>> Jan Algermissen
>>>
>>> Mail: algermissen@...
>>> Blog: http://algermissen.blogspot.com/
>>> Home: http://www.jalgermissen.com
>>> --------------------------------------
>>>
>>>
>>>
>>>
>
> --------------------------------------
> Jan Algermissen
>
> Mail: algermissen@...
> Blog: http://algermissen.blogspot.com/
> Home: http://www.jalgermissen.com
> --------------------------------------
>
>
>
>

Jan Algermissen wrote:
> On Jan 13, 2010, at 5:06 PM, Guilherme Silveira wrote:
>
>   
>> Jan, about the Link header, I wanted to ask earlier in another  
>> discussion but found it too offtopic. I can't see how I can use it  
>> (instead of atom links) to represent multiple links within a  
>> collection. For example, if I have a collection of cities and each  
>> city has its own URI, how could the Link header in a no-nasty way  
>> represent a "self" relation to each city?
>>     
>
> It can't. The Link header applies to the requested resource.
>
>   

Which is, in some (most?) situations, a good thing - because it 
discourages designs where resources are 'overlapped' (i.e. composites), 
and therefore promotes visibility.

- Mike

On Jan 13, 2010, at 5:30 PM, mike amundsen wrote:

> Jan:
>
> <snip>
> Is that a production use case? Can you share the complete hypermedia?
> </snip>
>
> the example i have in mind is behind a firewall. if you're interested,
> i can proly work up a quick sample to public view.

Sure.
But then - do not put additional work on your desk!!

Jan


>
> mca
> http://amundsen.com/blog/
>
>
>
>
> On Wed, Jan 13, 2010 at 11:23, Jan Algermissen <algermissen1971@... 
> > wrote:
>>
>> On Jan 13, 2010, at 5:11 PM, mike amundsen wrote:
>>
>>> Jan:
>>>
>>> <snip>
>>> For such cases I'd actually avoid the introduction of a link  
>>> semantic and
>>> use DELETE because the client would presumably already know it is  
>>> dealing
>>> with an order resource:
>>> </snip>
>>>
>>> In the case i gave, the rel value documentation instructs developers
>>> to use the DELETE method when activating the associated URI unless
>>> they are working with an agent that does not support the DELETE  
>>> method
>>> (Web browsers) in which case the  POST method is an acceptable
>>> alternative.
>>
>> Is that a production use case? Can you share the complete hypermedia?
>>
>> Jan
>>
>>
>>>
>>> mca
>>> http://amundsen.com/blog/
>>>
>>>
>>>
>>>
>>> On Wed, Jan 13, 2010 at 11:02, Jan Algermissen <algermissen1971@... 
>>> >
>>> wrote:
>>>>
>>>> Mike,
>>>>
>>>> On Jan 13, 2010, at 4:49 PM, mike amundsen wrote:
>>>>
>>>>> My current approach is to use existing media types (to take  
>>>>> advantage
>>>>> of their existing semantics) and add "rel" values as needed.
>>>>>
>>>>> I start by using the values already registered and available  
>>>>> [1,2] and
>>>>> supplement those with ones I create to meet the domain-specific  
>>>>> need.
>>>>> When I create my own, I use a rel value that is a resolve-able  
>>>>> URI and
>>>>> place helpful documentation at that URI. I'ved used the  
>>>>> following two
>>>>> formats in the past:
>>>>>
>>>>> rel="http://www.example.org/rels/cancel-order"
>>>>> rel="http://www.example.org/rels/purchasing#cancel-order"
>>>>
>>>> Just a comment:
>>>>
>>>> For such cases I'd actually avoid the introduction of a link  
>>>> semantic and
>>>> use DELETE because the client would presumably already know it is  
>>>> dealing
>>>> with an order resource:
>>>>
>>>> DELETE /orders/6
>>>>
>>>> As a rule of thumb I do this:
>>>>
>>>> When the domain operation in question ('cancel an order') maps o  
>>>> the base
>>>> semantics of an existing HTTP method use that method to gain the
>>>> visibility
>>>> advantages over using the generic POST. In the example, caching  
>>>> would (in
>>>> theory) benefit from the visibility of DELETE (as opposed to  
>>>> POST) by
>>>> knowing that all caches of that order resource could be flushed.
>>>>
>>>> Jan
>>>>
>>>>
>>>>>
>>>>> In the second example, a single document is available that lists
>>>>> several related rel values. It's a documentation optimization  
>>>>> only.
>>>>>
>>>>> [1] http://www.iana.org/assignments/link-relations/link-relations.xhtml
>>>>> [2] http://dublincore.org/documents/dces/
>>>>>
>>>>> mca
>>>>> http://amundsen.com/blog/
>>>>>
>>>>>
>>>>>
>>>>>
>>>>> 2010/1/13 Felipe Ga�cho <fgaucho@...>:
>>>>>>
>>>>>> ok,
>>>>>>
>>>>>> I can use link "rel" to offer the client a list of possible  
>>>>>> next states
>>>>>> ....
>>>>>>
>>>>>> question: doing tat I expect the client to know what is the  
>>>>>> semantic
>>>>>> of each link, isn't it ?
>>>>>>
>>>>>> If yes, hateoas seems not feasible since the client needs a  
>>>>>> previous
>>>>>> knowledge about what to look for in the list of links...  
>>>>>> (unless there
>>>>>> is only one link, of course)
>>>>>>
>>>>>> the question is: can I create my own relation semantics ? or  
>>>>>> should I
>>>>>> grasp in the available ones for Atom and Xhtml in case I want to
>>>>>> produce HATEOAS systems?
>>>>>>
>>>>>> * I am trying to implement HATEOAS using Jersey.. I know it has  
>>>>>> no
>>>>>> support out of the box, so I am designing some tricks here :)
>>>>>>
>>>>>> regards,
>>>>>>
>>>>>>
>>>>>>  Felipe Ga�cho
>>>>>>
>>>>>>
>>>>>> ------------------------------------
>>>>>>
>>>>>> Yahoo! Groups Links
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>> ------------------------------------
>>>>>
>>>>> Yahoo! Groups Links
>>>>>
>>>>>
>>>>>
>>>>
>>>> --------------------------------------
>>>> Jan Algermissen
>>>>
>>>> Mail: algermissen@...
>>>> Blog: http://algermissen.blogspot.com/
>>>> Home: http://www.jalgermissen.com
>>>> --------------------------------------
>>>>
>>>>
>>>>
>>>>
>>
>> --------------------------------------
>> Jan Algermissen
>>
>> Mail: algermissen@...
>> Blog: http://algermissen.blogspot.com/
>> Home: http://www.jalgermissen.com
>> --------------------------------------
>>
>>
>>
>>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

--------------------------------------
Jan Algermissen

Mail: algermissen@acm.org
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

For extensibility reasons, link relation type values can be URIs. In fact, if the link relation type is not a registered type, URIs are better. Such types are called "extension relation types".

begin shameless-plugin-motivated-by-jim-webber-:)
  See recipe 5.4 in http://my.safaribooksonline.com/9780596809140
end

Also see http://tools.ietf.org/html/draft-nottingham-http-link-header-06#section-4.2.

Subbu

On Jan 13, 2010, at 7:52 AM, Felipe Ga�cho wrote:

> Hi amundsen,
> 
> you are using the relation  attribute for the navigation.. strange..
> 
> relation should just give the client a hint about the relation between
> a resource and the url in the link element.. not a URI itself..
> 
> imho..
> 
> I got the point about the original question, thanks a lot for all responses.
> 
> 
>   Felipe Ga�cho.
> 
> 2010/1/13 mike amundsen <mamund@...>:
>> My current approach is to use existing media types (to take advantage
>> of their existing semantics) and add "rel" values as needed.
>> 
>> I start by using the values already registered and available [1,2] and
>> supplement those with ones I create to meet the domain-specific need.
>> When I create my own, I use a rel value that is a resolve-able URI and
>> place helpful documentation at that URI. I'ved used the following two
>> formats in the past:
>> 
>> rel="http://www.example.org/rels/cancel-order"
>> rel="http://www.example.org/rels/purchasing#cancel-order"
>> 
>> In the second example, a single document is available that lists
>> several related rel values. It's a documentation optimization only.
>> 
>> [1] http://www.iana.org/assignments/link-relations/link-relations.xhtml
>> [2] http://dublincore.org/documents/dces/
>> 
>> mca
>> http://amundsen.com/blog/
>> 
>> 
>> 
>> 
>> 2010/1/13 Felipe Ga�cho <fgaucho@...>:
>>> ok,
>>> 
>>> I can use link "rel" to offer the client a list of possible next states ....
>>> 
>>> question: doing tat I expect the client to know what is the semantic
>>> of each link, isn't it ?
>>> 
>>> If yes, hateoas seems not feasible since the client needs a previous
>>> knowledge about what to look for in the list of links... (unless there
>>> is only one link, of course)
>>> 
>>> the question is: can I create my own relation semantics ? or should I
>>> grasp in the available ones for Atom and Xhtml in case I want to
>>> produce HATEOAS systems?
>>> 
>>> * I am trying to implement HATEOAS using Jersey.. I know it has no
>>> support out of the box, so I am designing some tricks here :)
>>> 
>>> regards,
>>> 
>>> 
>>>    Felipe Ga�cho
>>> 
>>> 
>>> ------------------------------------
>>> 
>>> Yahoo! Groups Links
>>> 
>>> 
>>> 
>>> 
>> 
> 
> 
> 
> -- 
> ------------------------------------------
>   Felipe Ga�cho
>   10+ Java Programmer
>   CEJUG Senior Advisor
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

Hi Eb,

> Why would this make a difference?  We keep talking about reach, but most (if
> not all?) media types were designed for a specific client. 

Or clients. Atom has reach because lots of systems out there already understand how to process it.

application/vnd.restbucks+xml does not have reach because there aren't many systems out there that understand it. Nor are there lots of libraries to choose from on lots of platforms that implement the processing model for that type. But it does have the advantage that it works really well for coffee ordering within the Restbucks domain.

Jim

> Which is, in some (most?) situations, a good thing - because it discourages
> designs where resources are 'overlapped' (i.e. composites), and therefore
> promotes visibility.

Hello Mike,

If I avoid using a nested element that overlaps another resource
representation, as mentioned, how can a client understand the any
difference between an order products and its other related resources
and act acorrdingly? Or the client should not know how to add products
to this order?

<order>
  <link rel="related" href="http://server/products" /> (or similar header)
  <link rel="related" href="http://server/similar-orders" /> (or similar header)
 </order>

In the human web, the client reads "products" instead of "related"
prior to acting upon a representation, in a M2M system, it should not?

If there was a link describing a products relationship (with its
namespace), the client knows how to deal with it.

Regards

>
> - Mike
>

Hey Jim -

Or clients. Atom has reach because lots of systems out there already
> understand how to process it.
>
> application/vnd.restbucks+xml does not have reach because there aren't many
> systems out there that understand it. Nor are there lots of libraries to
> choose from on lots of platforms that implement the processing model for
> that type. But it does have the advantage that it works really well for
> coffee ordering within the Restbucks domain.
>
>
But what type(s) of systems are we really talking about here?  Could we
classify/aggregate them?  I would love to see example of business systems
that just use (for example) Atom as is with no extensions.  It would seem to
me that the semantics (from a registered link relations perspective)
available in Atom (as is) is limited in reach whereas most business
applications have a much richer vocabulary.

I would love to be completely off base here!! :)

Eb

>
> > It would seem to me that the semantics (from a registered link relations
> perspective) available in Atom (as is) is limited in reach whereas most
> business applications have a much richer vocabulary.
>
As per my example on the previous message:
<order>
 <link rel="related" href="http://server/products" /> (or similar header)
 <link rel="related" href="http://server/similar-orders" /> (or similar
header)
 </order>

Atom (and link headers) following only registered link relations would only
allow  representations as the above?

Regards

>
> I would love to be completely off base here!! :)
>
> Eb
>
>  
>

On Jan 13, 2010, at 8:45 AM, Jim Webber wrote:

> application/vnd.restbucks+xml does not have reach because there aren't many systems out there that understand it. Nor are there lots of libraries to choose from on lots of platforms that implement the processing model for that type. But it does have the advantage that it works really well for coffee ordering within the Restbucks domain.

I started with the same premise about 15 months ago, but later on found some bumps that made me change my mind. As long as  "application/vnd.restbucks+xml" is the only variant, I think you are right. No other party except the sender and the receiver need to deal with the name and semantics of this media type.

However, once the application requires any other party (proxies, CDNs, monitoring tools, log file analyzers etc.) understand such media types, this model starts to fall apart. All such tools will be more than happy to oblige URI patterns and not media types. This is not a media type problem, but a potential reality that Restbucks Inc. may need to account for.

Subbu

Hello Subbu -

I started with the same premise about 15 months ago, but later on found some
> bumps that made me change my mind. As long as
> "application/vnd.restbucks+xml" is the only variant, I think you are right.
> No other party except the sender and the receiver need to deal with the name
> and semantics of this media type.
>
> However, once the application requires any other party (proxies, CDNs,
> monitoring tools, log file analyzers etc.) understand such media types, this
> model starts to fall apart. All such tools will be more than happy to oblige
> URI patterns and not media types. This is not a media type problem, but a
> potential reality that Restbucks Inc. may need to account for.
>
>
I like this point.  From a reach perspective, we should think more of the
other agents/intermediaries that would have no clue on how to handle this
media type (if they needed too).  Regardless, the receiver (in a lot of
cases) will need to understand the extensions to an existing media type.

<order>
>  <link rel="related" href="http://server/products" /> (or similar header)
>  <link rel="related" href="http://server/similar-orders" /> (or similar
> header)
>  </order>
>
> Atom (and link headers) following only registered link relations would only
> allow  representations as the above?
>
>
I'm not sure I understand the question in its entirety, but your relation
(rel) would/could be a URI (and not "related") allowing a client to
distinguish between the two link relations.

Hey Eb,

> I like this point.  From a reach perspective, we should think more of the
> other agents/intermediaries that would have no clue on how to handle this
> media type (if they needed too).  Regardless, the receiver (in a lot of
> cases) will need to understand the extensions to an existing media type.

If a client or intermediary doesn't understand a media type then all bets are off - the client or intermediary doesn't understand the service's contract.

Some clients know about lots of media types (e.g. browsers) some clients know about few media types (e.g. Restbucks systems). That's the essence of reach.

Jim

Guilherme Silveira wrote:
>> Which is, in some (most?) situations, a good thing - because it discourages
>> designs where resources are 'overlapped' (i.e. composites), and therefore
>> promotes visibility.
>>     
>
> Hello Mike,
>
> If I avoid using a nested element that overlaps another resource
> representation, as mentioned, how can a client understand the any
> difference between an order products and its other related resources
> and act acorrdingly?

Using distinctive rel values for each type of link relation - your 
example doesn't do this:

> Or the client should not know how to add products
> to this order?
>
> <order>
>   <link rel="related" href="http://server/products" /> (or similar header)
>   <link rel="related" href="http://server/similar-orders" /> (or similar header)
>  </order>
>
> In the human web, the client reads "products" instead of "related"
> prior to acting upon a representation, in a M2M system, it should not?

Sorry, I don't understand the question

I think those rel values are wrong, a 'related' link relation doesn't 
really say much.. Maybe something like this instead:

<order>
  <link rel="products" href="http://server/products" /> (or similar header)
  <link rel="similar" href="http://server/similar-orders" /> (or similar header)
</order>


?

- Mike

Hey Jim  -


> If a client or intermediary doesn't understand a media type then all bets
> are off - the client or intermediary doesn't understand the service's
> contract.
>
> Some clients know about lots of media types (e.g. browsers) some clients
> know about few media types (e.g. Restbucks systems). That's the essence of
> reach.
>

I concur however, its sorta assumed that my client will understand the media
becuase I had to take the media type into consideration from the get go.  I
probably won't think (or care about) intermediaries depending on the "reach"
of my solution, intranet versus internet for example.  So when we suggest
using "standard" media types for purposes of reach, we just need to be clear
as to what concerns we're focusing on.

Eb

> Sorry, I don't understand the question
Sorry, I couldnt come up with the question so clearly.

> I think those rel values are wrong, a 'related' link relation doesn't really
> say much.. Maybe something like this instead:
So do I, but creating such custom relations and sticking to a well
known media type (an atom feed containing this order, for example)
does or does not break the reach issue that Subbu mentioned?

Proxies, log tools and so on can understand atom based resources but
not "http://server/products" rels.

> <order>
> �<link rel="http://server/products" href="http://server/products" /> (or similar header)
> �<link rel="http://server/similar" href="http://server/similar-orders" /> (or similar
> header)
> </order>

Regards


>
>
> ?
>
> - Mike
>

Subbu,

On Jan 13, 2010, at 7:29 PM, Subbu Allamaraju wrote:

> However, once the application requires any other party (proxies,  
> CDNs, monitoring tools, log file analyzers etc.) understand such  
> media types, this model starts to fall apart. All such tools will be  
> more than happy to oblige URI patterns and not media types. This is  
> not a media type problem, but a potential reality that Restbucks  
> Inc. may need to account for.


Can you provide an example of the situation that made you change your  
mind?


jan



--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

Reach can be double-edged.  If you assume no one outside of your sphere of
expertise will care but your service is widely popular in the wild, you're
going to be somewhat stuck with the assumption.

This wouldn't be the first time[1] this has happened.

-Noah

[1]
http://www.theaustralian.com.au/news/web-creator-apologises-for-his-strokes/story-e6frgal6-1225786657345

On Wed, Jan 13, 2010 at 12:15 PM, Eb <amaeze@...> wrote:

>
>
>
> Hey Jim  -
>
>
>>  If a client or intermediary doesn't understand a media type then all bets
>> are off - the client or intermediary doesn't understand the service's
>> contract.
>>
>> Some clients know about lots of media types (e.g. browsers) some clients
>> know about few media types (e.g. Restbucks systems). That's the essence of
>> reach.
>>
>
> I concur however, its sorta assumed that my client will understand the
> media becuase I had to take the media type into consideration from the get
> go.  I probably won't think (or care about) intermediaries depending on the
> "reach" of my solution, intranet versus internet for example.  So when we
> suggest using "standard" media types for purposes of reach, we just need to
> be clear as to what concerns we're focusing on.
>
> Eb
>
>
> 

--- In rest-discuss@yahoogroups.com, Jim Webber <jim@...> wrote:
>
> Hey Eb,
> 
> > I like this point.  From a reach perspective, we should think more of the
> > other agents/intermediaries that would have no clue on how to handle this
> > media type (if they needed too).  Regardless, the receiver (in a lot of
> > cases) will need to understand the extensions to an existing media type.
> 
> If a client or intermediary doesn't understand a media type then all bets are off - the client or intermediary doesn't understand the service's contract.
> 
> Some clients know about lots of media types (e.g. browsers) some clients know about few media types (e.g. Restbucks systems). That's the essence of reach.
> 
> Jim
>

I keep coming back to this on this list from different angles -- so appologies if I sound redundant, but I always get the feeling that folks don't quite get where I'm coming from -- I keep trying because I think this is an important point for understanding REST and this list contains the set of key individuals educating the broader development community. 

Is the media type a part of the service's contract or the client's?

It seems to me that a key distinction between REST and RPC is that in RPC the service provides the contract while in REST, the client provides the contract (via the media type).

A client, in the Accept header, constrains the set of acceptable media types -- isn't this essentially run-time contract negotiation?
The server agrees to the contract at run time by returning an appropriate representation of the requested resource (or rejects the contract by returning "Not Acceptable").

*Typically*, services can easily extend their "reach" by supporting as many media types as they like while clients support a fixed set of media types. So in order to give a client reach, it is best to support media types that are able to be used by a broad range of services.

For example, HTML can obviously be used to express an incredible range of services. VoiceXML (used by automated phone systems) can also be used to express a broad range of services. Supporting one of these media types would give a client a broad reach as it could interact with many services. But a service could address both HTML and VoiceXML clients via conneg (or simply two disjoint sets of URIs).

Isn't this the root of the client-server decoupling provided by REST?

If so -- then the question I keep coming back to is if a service that uses a "service-specific" media type is really an instance of REST. By service-specific, I don't mean "not standardized" or vendor-specific -- this has nothing to do with the nature of the media type itself, just whether or not it's been approved by a standards body. I mean that the media type represents a contract set by the service because the media type is not designed to represent a set of services. This is because the semantics of the media type map exactly to the semantics of the service. You see this in most "REST APIs" that are simply serializing service data structures as JSON or XML.

To me a RESTful service "translates" it's own internal semantics into the media type(s) of the client(s) it is trying to address -- the specific translation used being negotiated at runtime. This, to me is the point of having a distinction between resources and representations in REST. The translation doesn't just allow the service to "reach" a broader set of clients, but it also allows the client to "reach" a broader set of services. This is because the representation format captures information using semantics that are specific to the client. By designing the client's format around the information processing capabilities of the client, the client can interact with as many services as possible.

For example, HTML represents information in terms of common structures of visually displayed, interactive text -- it's designed around visual browsers. VoiceXML is designed around voice browsers. Yes, you can write a spider to consume HTML (and VoiceXML). And yes, you can use a screen reader to process HTML, but VoiceXML is a much more natural way to represent information for speech-based consumption and interaction (it won a standards war with SALT -- a set of extensions to HTML for speech). So there are other ways to consume the information (something afforded by the Principle of Least Power), but that doesn't diminish the fact that the media type is designed to cater to a specific flavor of client.

So when a media type is designed around a service rather than a type of client, I question if the result can be called REST. For example, a banking service that spits out a JSON format that simply serializes the account and transaction data structures used internally to represent the service's resources. i.e. if you aren't targeting a specific "type" of client by translating to that client's media type are you violating the constraints of REST? 

What specific constraints are being violated is a hard question and the reason I have a hard time explaining this -- I would point to "Self-descriptive messages" and its requirement for standard media types but the meaning of "standard" in the context of REST is so hard to pin down. Or maybe this is just inherent in the distinction between representations and resources.

Or maybe this isn't part of REST's constraints at all... I don't know -- that's why I keep asking (but based on the answers I get, I don't think I ever get the question across properly). Anyways, I'm interested in all of your thoughts.
Regards,

Andrew

I think Atom provides a great primitive for collections in an organization
and the syndication around those primitives.  It's not a complete solution,
but if you take the HTML/microformat, ATOM as a base you can probably build
quite a bit.

On Wed, Jan 13, 2010 at 10:23 AM, Eb <amaeze@...> wrote:

>
>
> Hey Jim -
>
>
>  Or clients. Atom has reach because lots of systems out there already
>> understand how to process it.
>>
>> application/vnd.restbucks+xml does not have reach because there aren't
>> many systems out there that understand it. Nor are there lots of libraries
>> to choose from on lots of platforms that implement the processing model for
>> that type. But it does have the advantage that it works really well for
>> coffee ordering within the Restbucks domain.
>>
>>
> But what type(s) of systems are we really talking about here?  Could we
> classify/aggregate them?  I would love to see example of business systems
> that just use (for example) Atom as is with no extensions.  It would seem to
> me that the semantics (from a registered link relations perspective)
> available in Atom (as is) is limited in reach whereas most business
> applications have a much richer vocabulary.
>
> I would love to be completely off base here!! :)
>
> Eb
>
>
> 

> However, once the application requires any other party (proxies, CDNs, 
> monitoring tools, log file analyzers etc.) understand such media types, 
> this model starts to fall apart.

I read your blog post about that and it certainly also made me re-think the 
use of media types like application/vnd.mystuff+xml (custom media types) and 
application/vnd.mystuff.v2+xml (versioning). An XML purchase order or movie 
representation is after all still XML.

On the other hand one still need some header to switch on when dispatching 
the returned representation. Aren't there other HTTP headers which can be 
used for indicating sub-media-types and versions?

Some things I dislike about the use of putting versioning and formating in 
the URL is 1) you no longer have a single ressource, 2) server logic needs 
to template embedded links based on the current URL. Example:

  URL 1: http://example.com/movies/1.xml
  URL 2: http://example.com/movies/1.json

Each of these movie representations have relations to other ressources, but 
the ressource at URL 1 should link to the .xml versions, and the ressource 
at URL 2 should link to the .json versions and so on. It's much easier if 
all URL's are without format-extensions (as well as version-extensions).

/J�rn

> So when a media type is designed around a service rather than a type of 
> client, I question if the result can be called REST. For example, a 
> banking service that spits out a JSON format that simply serializes the 
> account and transaction data structures used internally to represent the 
> service's resources. i.e. if you aren't targeting a specific "type" of 
> client by translating to that client's media type are you violating the 
> constraints of REST?

I like this formulation of the problem. Yes, the service is sort-of 
targeting itself instead of it's users. But are there any alternatives?

It is as if the smaller your audience is, the more are you violating REST. 
Example: the detailed representation of a egyptic scarabae collection - 
there's probably not many who are going to consume that. Is it not RESTful 
to have a special XML (maybe even binary) representation of that?

There are people on this list who argue that representaions must be accepted 
as standards in order to call the service RESTful. Considering the above 
thoughts they have a good point: it would not matter if the audience for a 
representation was big or small, as long as it has a standard 
representation. Then banking clients works for all banks and scarabae 
collectors can browse any scarabae collection on the net.

Maybe we could simplify the problem a bit: 1) we cannot expect each and 
every client to know all standard media-types, and 2) some media-types, like 
the scarabae collection, are just too specialized to get accepted as a 
standard media-type. So what if a service could be categorized as RESTful 
*with respect to a certain domain*?

Now we could say that our scarabae service certainly is RESTful with respect 
to the scarabae domain - and similar with the banking example.

Then we could use URL's for domain identifiers and have those URL's return a 
(standard) representation of the media types included in the domain.

But maybe I'm just dreaming and should go to bed instead ...

/J�rn 

On Jan 13, 2010, at 10:09 PM, wahbedahbe wrote:

>
> Is the media type a part of the service's contract or the client's?
>
> It seems to me that a key distinction between REST and RPC is that  
> in RPC the service provides the contract while in REST, the client  
> provides the contract (via the media type).
>
> A client, in the Accept header, constrains the set of acceptable  
> media types -- isn't this essentially run-time contract negotiation?
> The server agrees to the contract at run time by returning an  
> appropriate representation of the requested resource (or rejects the  
> contract by returning "Not Acceptable").

When you build a client that understands media type A, you need to  
hard wire (or configure) two things into your client code:

1. knowledge about which hypermedia elements are traversal options
    (links, forms)
2. knowledge about which media types to put into the Accept header
    when the user (human or machine) of the client chooses to follow
    a certain transition. (You do *not* code the client to simply list
    all the media types it understands)

During the request handling, there happens runtime negotiation of the  
content but there is a piece of contract that is a design time  
artifact (2. above). The question really is: On the basis of what  
information does the client choose what types to put in the Accept  
header. It is not an arbitrary decision but a decision that  
essentially reflects the client's design-time knowledge of the domain  
protocol supported by the service.

>
> *Typically*, services can easily extend their "reach" by supporting  
> as many media types as they like while clients support a fixed set  
> of media types. So in order to give a client reach, it is best to  
> support media types that are able to be used by a broad range of  
> services.

I think it is the other way round: Services expect the clients to  
understand a set of media types. This set constitutes the service's  
type.

>
> For example, HTML can obviously be used to express an incredible  
> range of services.

Hmm - I'd argue that HTML oly expresses the semantics needed by a  
browser to turn human targetted hypermedia into an interactive GUI.  
The 'incredible range' is a by-product of humans controlling the  
browser.

> VoiceXML (used by automated phone systems) can also be used to  
> express a broad range of services. Supporting one of these media  
> types would give a client a broad reach as it could interact with  
> many services. But a service could address both HTML and VoiceXML  
> clients via conneg (or simply two disjoint sets of URIs).

Hmm, not sure I understand that. Can you illustrate?

>
> Isn't this the root of the client-server decoupling provided by REST?

The decoupling is achieved by removing *any* assumption on the client  
side about what the server may do next. (Except for, for example,  
returning images for requests to <img href=""> target URIs. The server  
must not contradict itself.

In my posting regarding testing a couple of days ago I tried to  
'investigate' the point by saying: "A server can never send a wrong  
response" client's must expect anything. (See Jim's excellent point  
about 'anything' being constrained by the used media types).

>
> If so -- then the question I keep coming back to is if a service  
> that uses a "service-specific" media type is really an instance of  
> REST. By service-specific, I don't mean "not standardized" or vendor- 
> specific -- this has nothing to do with the nature of the media type  
> itself, just whether or not it's been approved by a standards body.  
> I mean that the media type represents a contract set by the service  
> because the media type is not designed to represent a set of  
> services. This is because the semantics of the media type map  
> exactly to the semantics of the service. You see this in most "REST  
> APIs" that are simply serializing service data structures as JSON or  
> XML.

JSON or XML media types can never 'transport' the semantics of a  
certain service or domain. They are so generic that they are useless  
from a media type discussion POV. Maybe you are criticising the use of  
such generic types and not really the issue of media types designed  
for a certain application?

Also, I think it is very important to diferentiate between service  
types and service instances. This is sometimes hard to do when you  
look at the Web because there are mostly services that are unique (are  
instances of their own type). But services that implement AtomPub are  
*instances* of the kind of service defined by RFC5023. This is why you  
can implement AtomPub clients without looking at a service instance.

I do think that certain problem domains (or service types) need their  
own media types (maybe mixed with existing types). But, yes, I agree  
that a media type should be designed for a set of services (aka type?)  
and not for a single one.

OTH, when Google provides a set of quasi-standardized extensions when  
publishing a service - that is fine. How's that different from Google  
minting a few types for the job?


>
> To me a RESTful service "translates" it's own internal semantics  
> into the media type(s) of the client(s) it is trying to address --

I would rather say: A service expects clients to understand certain  
types. If known-to-be-supported types do not do the job, then mint new  
types or extensions and publish them and hope clients implement them.

> the specific translation used being negotiated at runtime. This, to  
> me is the point of having a distinction between resources and  
> representations in REST. The translation doesn't just allow the  
> service to "reach" a broader set of clients, but it also allows the  
> client to "reach" a broader set of services. This is because the  
> representation format captures information using semantics that are  
> specific to the client. By designing the client's format around the  
> information processing capabilities of the client, the client can  
> interact with as many services as possible.

But you cannot magically make a client understand a semantic needed to  
express your (the server's) state machine.

>
> For example, HTML represents information in terms of common  
> structures of visually displayed, interactive text -- it's designed  
> around visual browsers. VoiceXML is designed around voice browsers.  
> Yes, you can write a spider to consume HTML (and VoiceXML). And yes,  
> you can use a screen reader to process HTML, but VoiceXML is a much  
> more natural way to represent information for speech-based  
> consumption and interaction (it won a standards war with SALT -- a  
> set of extensions to HTML for speech). So there are other ways to  
> consume the information (something afforded by the Principle of  
> Least Power), but that doesn't diminish the fact that the media type  
> is designed to cater to a specific flavor of client.
>
> So when a media type is designed around a service rather than a type  
> of client, I question if the result can be called REST. For example,  
> a banking service that spits out a JSON format that simply  
> serializes the account and transaction data structures used  
> internally to represent the service's resources. i.e. if you aren't  
> targeting a specific "type" of client by translating to that  
> client's media type are you violating the constraints of REST?

Hmm - are you trying to say that media types should be design for a  
kind of application (online purchasing, online bank account management  
etc.)? If so - yes, of course!


>
> What specific constraints are being violated is a hard question and  
> the reason I have a hard time explaining this

Sounds like you are talking about visibility in a sense. At least  
putting application specific stuff into generoc formats and relying on  
out-of-band contracts to fill the void violates the visibility  
constraint.

> -- I would point to "Self-descriptive messages" and its requirement  
> for standard media types but the meaning of "standard" in the  
> context of REST is so hard to pin down. Or maybe this is just  
> inherent in the distinction between representations and resources.

> "Self-descriptive messages" are another form of saying 'visibility'.

>
> Or maybe this isn't part of REST's constraints at all... I don't  
> know -- that's why I keep asking (but based on the answers I get, I  
> don't think I ever get the question across properly). Anyways, I'm  
> interested in all of your thoughts.

Hope they help.

Jan



> Regards,
>
> Andrew
>
>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

On Jan 13, 2010, at 10:46 PM, J�rn Wildt wrote:

> It is as if the smaller your audience is, the more are you violating  
> REST.


Put it this way: The smaller your audience is the more you have to get  
the job done with what they already have to grow until the audience is  
large anough to roll your own and force it into their implementations.

Jan

J

On Wed, Jan 13, 2010 at 5:20 PM, Jan Algermissen <algermissen1971@...m>wrote:

>
>
>
> On Jan 13, 2010, at 10:46 PM, J�rn Wildt wrote:
>
> > It is as if the smaller your audience is, the more are you violating
> > REST.
>
> Put it this way: The smaller your audience is the more you have to get
> the job done with what they already have to grow until the audience is
> large anough to roll your own and force it into their implementations.
>
>
Jan, I'm not so sure I get your point here.  Could you elaborate?

On Jan 13, 2010, at 12:55 PM, Jan Algermissen wrote:

> Subbu,
> 
> On Jan 13, 2010, at 7:29 PM, Subbu Allamaraju wrote:
> 
>> However, once the application requires any other party (proxies, CDNs, monitoring tools, log file analyzers etc.) understand such media types, this model starts to fall apart. All such tools will be more than happy to oblige URI patterns and not media types. This is not a media type problem, but a potential reality that Restbucks Inc. may need to account for.
> 
> 
> Can you provide an example of the situation that made you change your mind?

Say, the server offers books and CDs with media types application/vnd.book.myformat and application/vnd.cd.myformat. The task of an ops engineer is to quickly come up with daily charts showing requests/day for books and CDs, by sifting through access logs. It is easy to implement this when the URIs used for these types of resources have stable patterns. 

Let's say, you now want to run all CD sales (POST requests) through a bigger box. URI patterns rule again. 

Both these are solvable based on media types, but when I design my application such that some key factors are reflected in URIs (and a few known media types), I get much more mileage out of the HTTP toolstack. If I start folding these into an elaborate media type scheme, I will be fighting with the toolstack to get it to work for me. In the long run, it may even cost more to maintain such a system.

In other words, media types (along with URIs, content encodings, charset params etc.) keep representation visible to the protocol and the toolstack. But that does not necessarily follow that media types must be used to determine whether an incoming XML document is a book or a CD. There are other (simpler) ways to determine such things.

Subbu

FWIW, I find this always a "good read" when I start contemplating
media-type related issues:
http://www.ics.uci.edu/~fielding/pubs/dissertation/evaluation.htm#sec_6_5_4

mca
http://amundsen.com/blog/




On Wed, Jan 13, 2010 at 18:09, Subbu Allamaraju <subbu@...> wrote:
>
> On Jan 13, 2010, at 12:55 PM, Jan Algermissen wrote:
>
>> Subbu,
>>
>> On Jan 13, 2010, at 7:29 PM, Subbu Allamaraju wrote:
>>
>>> However, once the application requires any other party (proxies, CDNs, monitoring tools, log file analyzers etc.) understand such media types, this model starts to fall apart. All such tools will be more than happy to oblige URI patterns and not media types. This is not a media type problem, but a potential reality that Restbucks Inc. may need to account for.
>>
>>
>> Can you provide an example of the situation that made you change your mind?
>
> Say, the server offers books and CDs with media types application/vnd.book.myformat and application/vnd.cd.myformat. The task of an ops engineer is to quickly come up with daily charts showing requests/day for books and CDs, by sifting through access logs. It is easy to implement this when the URIs used for these types of resources have stable patterns.
>
> Let's say, you now want to run all CD sales (POST requests) through a bigger box. URI patterns rule again.
>
> Both these are solvable based on media types, but when I design my application such that some key factors are reflected in URIs (and a few known media types), I get much more mileage out of the HTTP toolstack. If I start folding these into an elaborate media type scheme, I will be fighting with the toolstack to get it to work for me. In the long run, it may even cost more to maintain such a system.
>
> In other words, media types (along with URIs, content encodings, charset params etc.) keep representation visible to the protocol and the toolstack. But that does not necessarily follow that media types must be used to determine whether an incoming XML document is a book or a CD. There are other (simpler) ways to determine such things.
>
> Subbu
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

On Jan 14, 2010, at 12:09 AM, Subbu Allamaraju wrote:

> Let's say, you now want to run all CD sales (POST requests) through  
> a bigger box. URI patterns rule again.


See your point.

Thinking about it, I actually do not see any reason why an  
intermediary should not be able to learn at runtime what the URIs are  
that are used for the individual sales kinds. So knowing the pattern  
out of band is (in theory) not 100% necessary.


Gotta go, rest of the reply tomorrow.

Jan

BTW, why are the sales distiguishable by the URI of the POST target  
resource (the order processing resource I assume)?

On Wed, Jan 13, 2010 at 6:09 PM, Subbu Allamaraju <subbu@...> wrote:
>
>
>
> Say, the server offers books and CDs with media types
> application/vnd.book.myformat and application/vnd.cd.myformat. The task of
> an ops engineer is to quickly come up with daily charts showing requests/day
> for books and CDs, by sifting through access logs. It is easy to implement
> this when the URIs used for these types of resources have stable patterns.
> .
>
> 
>

But your custom media type doesn't preclude you from using URIs in this
particular case does it?  So yes, the result would be the same if the media
type were application/xml, would it not be?  I don't so how this is a reason
not to use a custom media type.  Maybe I'm missing something here.

> 
> 
> But your custom media type doesn't preclude you from using URIs in this particular case does it?  So yes, the result would be the same if the media type were application/xml, would it not be?  I don't so how this is a reason not to use a custom media type.  Maybe I'm missing something here.

You're not missing anything. For this example it _does not matter_ if your media type application/xml or foo/bar. 

Subbu

>
>
> You're not missing anything. For this example it _does not matter_ if your
> media type application/xml or foo/bar.
>
So sticking with atom (or header) links + custom rel + resource descriptive
uri seems would not interfere with the visibility for intermediate layers?

Regards


> Subbu
>
>  
>

On Wed, Jan 13, 2010 at 5:16 PM, Jan Algermissen <algermissen1971@...>wrote:

>
> On Jan 13, 2010, at 10:09 PM, wahbedahbe wrote:
>
>
>> Is the media type a part of the service's contract or the client's?
>>
>> It seems to me that a key distinction between REST and RPC is that in RPC
>> the service provides the contract while in REST, the client provides the
>> contract (via the media type).
>>
>> A client, in the Accept header, constrains the set of acceptable media
>> types -- isn't this essentially run-time contract negotiation?
>> The server agrees to the contract at run time by returning an appropriate
>> representation of the requested resource (or rejects the contract by
>> returning "Not Acceptable").
>>
>
> When you build a client that understands media type A, you need to hard
> wire (or configure) two things into your client code:
>
> 1. knowledge about which hypermedia elements are traversal options
>   (links, forms)
> 2. knowledge about which media types to put into the Accept header
>   when the user (human or machine) of the client chooses to follow
>   a certain transition. (You do *not* code the client to simply list
>   all the media types it understands)
>
> During the request handling, there happens runtime negotiation of the
> content but there is a piece of contract that is a design time artifact (2.
> above). The question really is: On the basis of what information does the
> client choose what types to put in the Accept header. It is not an arbitrary
> decision but a decision that essentially reflects the client's design-time
> knowledge of the domain protocol supported by the service.
>
> Agreed (I followed your recent thread on the matter closely! ;-). I would
argue that the "domain protocol supported by the service" is the media type
and rel definitions. Is that your view?

>
>
>> *Typically*, services can easily extend their "reach" by supporting as
>> many media types as they like while clients support a fixed set of media
>> types. So in order to give a client reach, it is best to support media types
>> that are able to be used by a broad range of services.
>>
>
> I think it is the other way round: Services expect the clients to
> understand a set of media types. This set constitutes the service's type.


That way doesn't seem to match the way it works on the web though. What are
the "types of services" on the web? Social media applications, customer
service applications, auction applications, banking applications, etc. Each
service type doesn't have it's own set of media types. They all use HTML
because, well that's what browsers support. If you want to expand your
service's reach beyond browsers you'd have to support the media type of the
client you are trying to reach.

>
>
>
>> For example, HTML can obviously be used to express an incredible range of
>> services.
>>
>
> Hmm - I'd argue that HTML oly expresses the semantics needed by a browser
> to turn human targetted hypermedia into an interactive GUI. The 'incredible
> range' is a by-product of humans controlling the browser.


Ya I'm familiar with the "human driven" vs. "machine driven" argument. I
don't agree with this line of thinking at all -- the problem is that the
"machine driven" media types in use are just plain bad -- one of their big
problem's is the fact they are service specific!


>
>
>  VoiceXML (used by automated phone systems) can also be used to express a
>> broad range of services. Supporting one of these media types would give a
>> client a broad reach as it could interact with many services. But a service
>> could address both HTML and VoiceXML clients via conneg (or simply two
>> disjoint sets of URIs).
>>
>
> Hmm, not sure I understand that. Can you illustrate?
>
>
Voice Browsers are used to deliver voice applications over the phone that
are authored using the VoiceXML markup language.
Rather that explain VoiceXML here, I'll point you do a short tutorial by
Dave Ragett: http://www.w3.org/Voice/Guide/

Now, say you have a customer service application and you want to let
customers interact with it over the web via an HTML browser and over the
phone using an automated voice response system. The core application
resources would likely be the same (user account resources, product
resources, support ticket resources, etc.) for both the HTML and VoiceXML
applications. You could use the same set of URIs for both and use conneg to
serve HTML to web browsers and VoiceXML to voice browsers or use separate
URI's to serve HTML and VoiceXML.



>
>
>> Isn't this the root of the client-server decoupling provided by REST?
>>
>
> The decoupling is achieved by removing *any* assumption on the client side
> about what the server may do next. (Except for, for example, returning
> images for requests to <img href=""> target URIs. The server must not
> contradict itself.
>
> In my posting regarding testing a couple of days ago I tried to
> 'investigate' the point by saying: "A server can never send a wrong
> response" client's must expect anything. (See Jim's excellent point about
> 'anything' being constrained by the used media types).
>
> Sure, but you are basically saying that the media type forms the contract
right? And I what I'm trying to get at here is that the media type is the
client's contract not the service's. In the customer support example above,
both VoiceXML and HTML are mandated by the respective clients. The service
is conforming to those media types in order to be able to interact with
those clients. The client is not coupled to the service at all -- just the
media type, URI and HTTP. The service has the freedom to support whatever
representations it chooses -- it is not coupled to any one client's media
type.


>
>> If so -- then the question I keep coming back to is if a service that uses
>> a "service-specific" media type is really an instance of REST. By
>> service-specific, I don't mean "not standardized" or vendor-specific -- this
>> has nothing to do with the nature of the media type itself, just whether or
>> not it's been approved by a standards body. I mean that the media type
>> represents a contract set by the service because the media type is not
>> designed to represent a set of services. This is because the semantics of
>> the media type map exactly to the semantics of the service. You see this in
>> most "REST APIs" that are simply serializing service data structures as JSON
>> or XML.
>>
>
> JSON or XML media types can never 'transport' the semantics of a certain
> service or domain. They are so generic that they are useless from a media
> type discussion POV. Maybe you are criticising the use of such generic types
> and not really the issue of media types designed for a certain application?
>

Well, even if properly you "named" the XML format (e.g. used
application/vnd.whatever+xml instead of application/xml) I think you still
have the same problem. The issue goes beyond the media type name -- I'm
talking about the format itself.


> Also, I think it is very important to diferentiate between service types
> and service instances. This is sometimes hard to do when you look at the Web
> because there are mostly services that are unique (are instances of their
> own type). But services that implement AtomPub are *instances* of the kind
> of service defined by RFC5023. This is why you can implement AtomPub clients
> without looking at a service instance.
>

Right... the clients conform to the spec. If my customer service example
above wanted to make a subset of its resources accessible to Atom+AtomPub
clients, say the customer support tickets, it could do so by supporting
those media types. Well, almost -- there's the whole can of worms of how to
represent the "content" or in this case, the support ticket data. Do you use
a foreign XML namespace in the <entry> or do you put it in <content> (the
extension vs. envelope question)? I'll avoid getting into that here, so
let's just say that the formats that compose the contract consist of AtomPub
plus the content format.

But again, I see the format as the client's contract. The service in my
example is chosing to support the Atom client type by adding Atom to its
supported media types. It's hard to see it that way with Atom because of the
whole mess caused by the embedded content format. The problem is that most
Atom services use a service-specific content format which makes the whole
thing service-specific in the end despite the use of Atom.


>
> I do think that certain problem domains (or service types) need their own
> media types (maybe mixed with existing types). But, yes, I agree that a
> media type should be designed for a set of services (aka type?) and not for
> a single one.
>
> OTH, when Google provides a set of quasi-standardized extensions when
> publishing a service - that is fine. How's that different from Google
> minting a few types for the job?
>
> I think some of Google's services would be way more RESTful if they'd used
established media types for the content. i.e. Atom feeds of vCards would
have been way better than what they implemented IMO.

>
>
>
>> To me a RESTful service "translates" it's own internal semantics into the
>> media type(s) of the client(s) it is trying to address --
>>
>
> I would rather say: A service expects clients to understand certain types.
> If known-to-be-supported types do not do the job, then mint new types or
> extensions and publish them and hope clients implement them.


Nope. Can't agree here. As already discussed, I just don't see REST that
way. For me, media types start with the client.

>
>
>  the specific translation used being negotiated at runtime. This, to me is
>> the point of having a distinction between resources and representations in
>> REST. The translation doesn't just allow the service to "reach" a broader
>> set of clients, but it also allows the client to "reach" a broader set of
>> services. This is because the representation format captures information
>> using semantics that are specific to the client. By designing the client's
>> format around the information processing capabilities of the client, the
>> client can interact with as many services as possible.
>>
>
> But you cannot magically make a client understand a semantic needed to
> express your (the server's) state machine.
>
> Ok.... challenge accepted -- give me an example problem and I'll try to
show you how to solve it. One rule: you'll need to be able to answer
detailed questions about the example client as well as the service.

>
>> For example, HTML represents information in terms of common structures of
>> visually displayed, interactive text -- it's designed around visual
>> browsers. VoiceXML is designed around voice browsers. Yes, you can write a
>> spider to consume HTML (and VoiceXML). And yes, you can use a screen reader
>> to process HTML, but VoiceXML is a much more natural way to represent
>> information for speech-based consumption and interaction (it won a standards
>> war with SALT -- a set of extensions to HTML for speech). So there are other
>> ways to consume the information (something afforded by the Principle of
>> Least Power), but that doesn't diminish the fact that the media type is
>> designed to cater to a specific flavor of client.
>>
>> So when a media type is designed around a service rather than a type of
>> client, I question if the result can be called REST. For example, a banking
>> service that spits out a JSON format that simply serializes the account and
>> transaction data structures used internally to represent the service's
>> resources. i.e. if you aren't targeting a specific "type" of client by
>> translating to that client's media type are you violating the constraints of
>> REST?
>>
>
> Hmm - are you trying to say that media types should be design for a kind of
> application (online purchasing, online bank account management etc.)? If so
> - yes, of course!
>
> Nope. I am saying that media types should be designed for kinds of clients.
This is the precedent set by HTML, VoiceXML, etc.


>
>
>> What specific constraints are being violated is a hard question and the
>> reason I have a hard time explaining this
>>
>
> Sounds like you are talking about visibility in a sense. At least putting
> application specific stuff into generoc formats and relying on out-of-band
> contracts to fill the void violates the visibility constraint.
>
>
>  -- I would point to "Self-descriptive messages" and its requirement for
>> standard media types but the meaning of "standard" in the context of REST is
>> so hard to pin down. Or maybe this is just inherent in the distinction
>> between representations and resources.
>>
>
>  "Self-descriptive messages" are another form of saying 'visibility'.
>>
>
> Maybe... visibility is a part of it, but I think this goes beyond
visibility. This also affects (and is perhaps more central to)
substitutability, modifiability, evolvability, reusability, etc.

>
>> Or maybe this isn't part of REST's constraints at all... I don't know --
>> that's why I keep asking (but based on the answers I get, I don't think I
>> ever get the question across properly). Anyways, I'm interested in all of
>> your thoughts.
>>
>
> Hope they help.
>
> Jan
>
> Thanks... this is a good conversation, even if we don't see things the same
way (yet!) ;-)

Regards,

Andrew

> Put it this way: The smaller your audience is the more you have to get
the job done with what they already have

Interesting point: the smaller audience, the lesser likelihood of them 
having existing code for your service, the bigger need to use existing 
standards? Makes sence. Start with a not-so-suitable-but-standard media-type 
to get people going quick and then introduce newer and better formats.

/J�rn

Hi Eb,

> I concur however, its sorta assumed that my client will understand the media
> becuase I had to take the media type into consideration from the get go.  

I agree. You have to bake knowledge of media type(s) and link relations into clients.

> I
> probably won't think (or care about) intermediaries depending on the "reach"
> of my solution, intranet versus internet for example.  So when we suggest
> using "standard" media types for purposes of reach, we just need to be clear
> as to what concerns we're focusing on.

1. Re-use of standard libraries for building consumers/services
2. Serendipitous re-use of services  

Jim

Hi Jim -


> 1. Re-use of standard libraries for building consumers/services
> 2. Serendipitous re-use of services
>
>
Good points, although I will observe that most of the "new" media types we
are discussing here are derivatives of existing media types.  So from a
tooling standpoint (standard libraries), I think it in many cases is a
wash.  Serendipitous re-use of services.  Interesting.

Eb

Hello Andrew -

On Wed, Jan 13, 2010 at 11:05 PM, Andrew Wahbe <andrew.wahbe@...>wrote:

>
>> Sure, but you are basically saying that the media type forms the contract
> right? And I what I'm trying to get at here is that the media type is the
> client's contract not the service's. In the customer support example above,
> both VoiceXML and HTML are mandated by the respective clients. The service
> is conforming to those media types in order to be able to interact with
> those clients. The client is not coupled to the service at all -- just the
> media type, URI and HTTP. The service has the freedom to support whatever
> representations it chooses -- it is not coupled to any one client's media
> type.
>


While I think I agree with you (to an extent), this does suggest that
clients are built in isolation which I do not believe is the case in
practice.  Maybe the mistake is that we should look at what capabilities the
client needs to have and then use (or create a new) a media type that
sufficiently expresses those capabilities.  I see media type as the
"language spoken" (excuse my poor expression) between a client and server
and for anything meaningful to happen, they must both speak the same
language.  From that perspective, a client is indirectly coupled (only) to
services that speak its media type(s) and vice versa.

Where this gets interesting is that it seems to me that for every standard
media type that exists, clients (and servers) have been hard wired to
understand the media type in the context that the media type was created
for.  Browsers were written to understand HTML for a purpose.  Sure, I can
use HTML (or XML or Atom) to represent anything I want but does that mean
that just because my service and browser and client agree on text/html that
my browser will be able to do anything meaningful with the representation if
the semantics have nothing to do with display (for example)?  I don't think
so.  This is why I would still have to document (out of band) the semantics
contained in my representation even if I used a standard media type.  Now
there are positives, such that the browser could possibly render aspects of
the representation etc etc, but that's not the major point at the moment.


As always, I would love to be corrected. :)


Eb

On Thu, Jan 14, 2010 at 5:28 AM, Eb <amaeze@...> wrote:

> Hello Andrew -
>
>
> On Wed, Jan 13, 2010 at 11:05 PM, Andrew Wahbe <andrew.wahbe@...>wrote:
>
>>
>>> Sure, but you are basically saying that the media type forms the contract
>> right? And I what I'm trying to get at here is that the media type is the
>> client's contract not the service's. In the customer support example above,
>> both VoiceXML and HTML are mandated by the respective clients. The service
>> is conforming to those media types in order to be able to interact with
>> those clients. The client is not coupled to the service at all -- just the
>> media type, URI and HTTP. The service has the freedom to support whatever
>> representations it chooses -- it is not coupled to any one client's media
>> type.
>>
>
>
> While I think I agree with you (to an extent), this does suggest that
> clients are built in isolation which I do not believe is the case in
> practice.


Well let's limit our set of examples to systems widely agreed to be RESTful.
It's certainly that way for HTML browsers. It is that way for "pure" AtomPub
clients *designed for content publishing* (where the content is HTML or
another standard format and there are no service-specific extensions). It is
also that way for VoiceXML browsers (though I'm not sure there is wide
agreement that they are RESTful though I tend to think that that is because
not enough people know about them).

This isn't the case with many M2M clients and services -- there the service
usually comes first or the client and service are built at the same time.
But here we also have folks like Roy and others routinely poking holes in
the services and declaring they aren't RESTful. And we also have folks
reaching the conclusion that there must be some fundamental limitations of
M2M services because they can't achieve the same client-server decoupling as
we see in the Web.

I'm proposing that there is no fundamental limitation in M2M services --
system designers are just going about it the wrong way because they are
designing their media types around the services instead of the clients. If
they instead started with a specific client in mind, and designed the media
type around the client they can achieve the same level of client-service
decoupling as in the HTML web. This isn't just my opinion -- I can point to
a (in progress) W3C XML format for M2M RESTful systems that is designed in
this way, and has many implementations shipping today from multiple vendors
that don't depend on any specific service. Anyone can design a service in
that format that can do anything expressible in the language. This is CCXML:
http://www.w3.org/TR/ccxml/

As I've said many times on this list -- you really ought to have a look at
CCXML. It's not the best example of a RESTful markup language possible (e.g.
like HTML it only uses GET and POST, etc.) but there's a lot to be learned
from it. And most importantly, it stands as a counter example to the
assertion that M2M clients are fundamentally different from "human driven"
clients when it comes to client-service decoupling....

Or maybe I'm way off base and just confused about this... Don't know -- I
haven't heard an argument to make me change my mind yet, but I'd genuinely
like to hear it if it's out there.


>   Maybe the mistake is that we should look at what capabilities the client
> needs to have and then use (or create a new) a media type that sufficiently
> expresses those capabilities.  I see media type as the "language spoken"
> (excuse my poor expression) between a client and server and for anything
> meaningful to happen, they must both speak the same language.  From that
> perspective, a client is indirectly coupled (only) to services that speak
> its media type(s) and vice versa.
>

Absolutely, HTML (and VoiceXML) are designed around the client's needs and
capabilities -- not a service's. The web browser is "coupled" the entire set
of services that are expressible in HTML -- that is a big set. It's not
coupled to any one service.


> Where this gets interesting is that it seems to me that for every standard
> media type that exists, clients (and servers) have been hard wired to
> understand the media type in the context that the media type was created
> for.  Browsers were written to understand HTML for a purpose.  Sure, I can
> use HTML (or XML or Atom) to represent anything I want but does that mean
> that just because my service and browser and client agree on text/html that
> my browser will be able to do anything meaningful with the representation if
> the semantics have nothing to do with display (for example)?  I don't think
> so.  This is why I would still have to document (out of band) the semantics
> contained in my representation even if I used a standard media type.  Now
> there are positives, such that the browser could possibly render aspects of
> the representation etc etc, but that's not the major point at the moment.
>
> Yup... if you are using a "standard" media type in a "non-standard" way
then you will forfeit interoperability. And this is where lots of folks are
going wrong with Atom -- using it to do something other than publish and
syndicate content. Sure you can introduce extensions to extend what a media
type can do, but if those extensions are "service-specific" then you won't
get general interoperability or client-service decoupling.


> As always, I would love to be corrected. :)
>
> Me too! ;-)


>
> Eb
>

Regards,

Andrew

On Wed, Jan 13, 2010 at 4:46 PM, J�rn Wildt <jw@...> wrote:

> So when a media type is designed around a service rather than a type of
>> client, I question if the result can be called REST. For example, a banking
>> service that spits out a JSON format that simply serializes the account and
>> transaction data structures used internally to represent the service's
>> resources. i.e. if you aren't targeting a specific "type" of client by
>> translating to that client's media type are you violating the constraints of
>> REST?
>>
>
> I like this formulation of the problem. Yes, the service is sort-of
> targeting itself instead of it's users. But are there any alternatives?
>
> It is as if the smaller your audience is, the more are you violating REST.
> Example: the detailed representation of a egyptic scarabae collection -
> there's probably not many who are going to consume that. Is it not RESTful
> to have a special XML (maybe even binary) representation of that?
>

Well is the concept of a egyptic scarabae collection native to the client or
the service or both? I'm arguing to only put concepts truly important to the
client in your media type. Represent things from the client's viewpoint not
the service's. Don't worry about over-customizing things things for a
certain type of client because a service has the freedom to support multiple
representation formats and thereby increase it's reach to more types of
clients.


> There are people on this list who argue that representaions must be
> accepted as standards in order to call the service RESTful. Considering the
> above thoughts they have a good point: it would not matter if the audience
> for a representation was big or small, as long as it has a standard
> representation. Then banking clients works for all banks and scarabae
> collectors can browse any scarabae collection on the net.
>

I'm not sure if standardization is exactly the same thing or not... it's a
tough one. For example, you could standardize an RPC interface couldn't you?
I think that the issues here are modifiability, evolvability, reusability
etc. and they are a function of what you are standardizing, not whether the
format/interface is standardized or not.


>
> Maybe we could simplify the problem a bit: 1) we cannot expect each and
> every client to know all standard media-types, and 2) some media-types, like
> the scarabae collection, are just too specialized to get accepted as a
> standard media-type. So what if a service could be categorized as RESTful
> *with respect to a certain domain*?
>

Well, it seems to me a RESTful "domain" is always associated with the media
type and client. For the HTML web, the domain is (primarily visual)
interactive information presentation. For the VoiceXML web it is (primarily
speech-driven) interactive information presentation. For the Atom(Pub) web
it is content syndication and publishing. A single service can be targeted
to multiple domains by supporting multiple media types.

Regards,

Andrew

On Thu, Jan 14, 2010 at 10:40 AM, Andrew Wahbe <andrew.wahbe@...>wrote:

>
> Yup... if you are using a "standard" media type in a "non-standard" way
> then you will forfeit interoperability. And this is where lots of folks are
> going wrong with Atom -- using it to do something other than publish and
> syndicate content. Sure you can introduce extensions to extend what a media
> type can do, but if those extensions are "service-specific" then you won't
> get general interoperability or client-service decoupling.
>
>
Yeah, I agree with this which is way I'm never satisfied with the generic
recommendation to use current media types (apart from existing tooling
benefits, which is not really the point here) during design.

On Wed, Jan 13, 2010 at 4:09 PM, Subbu Allamaraju <subbu@...> wrote:
>
> On Jan 13, 2010, at 12:55 PM, Jan Algermissen wrote:
>

> Say, the server offers books and CDs with media types
> application/vnd.book.myformat and application/vnd.cd.myformat. The
> task of an ops engineer is to quickly come up with daily charts
> showing requests/day for books and CDs, by sifting through access
> logs. It is easy to implement this when the URIs used for these
> types of resources have stable patterns.
>
> Let's say, you now want to run all CD sales (POST requests) through
> a bigger box. URI patterns rule again.
>
> Both these are solvable based on media types, but when I design my
> application such that some key factors are reflected in URIs (and a
> few known media types), I get much more mileage out of the HTTP
> toolstack. If I start folding these into an elaborate media type
> scheme, I will be fighting with the toolstack to get it to work for
> me. In the long run, it may even cost more to maintain such a
> system.

I am a fan of domain specific media types.  However, i have never
implemented a system that had just one URL and figured every thing out
from the mime type, which seems like what you are arguing against.
Every resource (each CD or book in your example) would have it's own
URI so routing and reporting on a per-resource basis is still straight
forward.

If the service implementer chooses to implement the service is such a
way that *it* can infer information about the requests from the URI
that is great. (I do it all the time.)  But clients and intermediates
outside of the service implementer's control should never be expected
to understand such implications.

> In other words, media types (along with URIs, content encodings,
> charset params etc.) keep representation visible to the protocol and
> the toolstack. But that does not necessarily follow that media types
> must be used to determine whether an incoming XML document is a book
> or a CD. There are other (simpler) ways to determine such things.

Media types don't just tell you the syntax (XML flavor, etc) of the
representation, they also indicate the semantics.

Even if a service chooses to have a separate URI for every
representation media types would still be useful.  An exclusively atom
client that makes a request, with 'Accept: application/atom+xml',
against an HTML only blog resource should get redirected to the atom
representation resource.  (Or perhaps a '406 Not Acceptable' response
with a 'alternate' link header pointing to the atom representation
resource.)  Using domain specific media types allows that such
behavior, while a generic media type approach precludes it.

Using both URIs and media types in concert allows clients to
continuously operate on constantly evolving services, and services to
evolve quite aggressively without breaking existing clients.

Peter

On Jan 14, 2010, at 12:09 AM, Subbu Allamaraju wrote:

>
> On Jan 13, 2010, at 12:55 PM, Jan Algermissen wrote:
>
>> Subbu,
>>
>> On Jan 13, 2010, at 7:29 PM, Subbu Allamaraju wrote:
>>
>>> However, once the application requires any other party (proxies,  
>>> CDNs, monitoring tools, log file analyzers etc.) understand such  
>>> media types, this model starts to fall apart. All such tools will  
>>> be more than happy to oblige URI patterns and not media types.  
>>> This is not a media type problem, but a potential reality that  
>>> Restbucks Inc. may need to account for.
>>
>>
>> Can you provide an example of the situation that made you change  
>> your mind?
>
> Say, the server offers books and CDs with media types application/ 
> vnd.book.myformat and application/vnd.cd.myformat. The task of an  
> ops engineer is to quickly come up with daily charts showing  
> requests/day for books and CDs, by sifting through access logs. It  
> is easy to implement this when the URIs used for these types of  
> resources have stable patterns.
>
> Let's say, you now want to run all CD sales (POST requests) through  
> a bigger box. URI patterns rule again.
>
> Both these are solvable based on media types, but when I design my  
> application such that some key factors are reflected in URIs (and a  
> few known media types), I get much more mileage out of the HTTP  
> toolstack. If I start folding these into an elaborate media type  
> scheme, I will be fighting with the toolstack to get it to work for  
> me. In the long run, it may even cost more to maintain such a system.

Hmm, without an intent to argue about the specific example, this  
sounds a bit far fetched to me. The routing issue could be solved by  
the server itself by simply providing the clients with different  
target URLs for CDs and books in the ordering form. This would also  
address the statistics issue (which I think is likely to be better  
solved by using the more sophisticated analytics engine of the backend  
system anyway)

>
> In other words, media types (along with URIs, content encodings,  
> charset params etc.) keep representation visible to the protocol and  
> the toolstack. But that does not necessarily follow that media types  
> must be used to determine whether an incoming XML document is a book  
> or a CD. There are other (simpler) ways to determine such things.

I think I do not understand why you argue that you cannot have both;  
why you think you have to trade REST benefits for achieving the goals  
you describe. The coupling created by making particular URI patterns  
known to intermediaries for analytics and routing seems to be a heavy  
trade off. Especially since once it is established and figured out by  
the developers it will just spread all over the place. I'd go a long  
way to maintain URI opaqueness.

Maybe I am not understanding you correctly, though.

Jan




>
> Subbu
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

On Jan 14, 2010, at 1:54 PM, Jan Algermissen wrote:

> I think I do not understand why you argue that you cannot have both; why you think you have to trade REST benefits for achieving the goals you describe. The coupling created by making particular URI patterns known to intermediaries for analytics and routing seems to be a heavy trade off. Especially since once it is established and figured out by the developers it will just spread all over the place. I'd go a long way to maintain URI opaqueness.

Heavy tradeoff because it makes the business achieve its goals? These are operational requirements that most real-world HTTP services deal with routinely. 

Subbu

On Jan 14, 2010, at 1:54 PM, Jan Algermissen wrote:

> I think I do not understand why you argue that you cannot have both; why you think you have to trade REST benefits for achieving the goals you describe. 

By the way, please don't take this as an argument for or against these media types. AS proven time and again, this is a hard problem for a number of reasons and the community has no clear consensus. I am only trying to point out that we can't take one view of architecture overtake the rest. Designing applications with awareness of how infrastructure works helps a long way.

Subbu

On Jan 14, 2010, at 11:41 PM, Subbu Allamaraju wrote:

>
> On Jan 14, 2010, at 1:54 PM, Jan Algermissen wrote:
>
>> I think I do not understand why you argue that you cannot have  
>> both; why you think you have to trade REST benefits for achieving  
>> the goals you describe. The coupling created by making particular  
>> URI patterns known to intermediaries for analytics and routing  
>> seems to be a heavy trade off. Especially since once it is  
>> established and figured out by the developers it will just spread  
>> all over the place. I'd go a long way to maintain URI opaqueness.
>
> Heavy tradeoff because it makes the business achieve its goals?

No, heavy trade off because the business goal could very easily (at  
least as far as your example goes) be achieved without introducing the  
coupling.

> These are operational requirements that most real-world HTTP  
> services deal with routinely.

Might be - but I understand you to be saying those business goals  
could not be achieved without making use of shared knowledge about URI  
patterns. I question that.

After all, the value of REST lies in the style-induced, guaranteed  
system properties and the short term price to be paid for that is  
considerably high. *Maybe* you gain some near time business advantage  
by breaking constraints but you are working against the long term goal  
that motivated the use of REST in the first place.

I am all against architectural purity for its own sake but the call  
for business level goals that justify anything is far too often made  
too quickly.

Jan

>
> Subbu

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

--- In rest-discuss@yahoogroups.com, "wahbedahbe" <andrew.wahbe@...> wrote:
> So when a media type is designed around a service rather than a type of client, I question if the result can be called REST. For example, a banking service that spits out a JSON format that simply serializes the account and transaction data structures used internally to represent the service's resources. i.e. if you aren't targeting a specific "type" of client by translating to that client's media type are you violating the constraints of REST? 

I keep comming back to this statement, you really got some thoughts starting. Thanks.

It also puts some light on the problems of using a framework like WCF REST for a REST server: In WCF REST the default representation of an object is it's standard XML/JSON serialization. It is very easy to just serialize your internal Data-Transfer-Objects and let that be the representation. In this case you really design around your own service instead of your clients.

/J�rn

On Fri, Jan 15, 2010 at 6:56 AM, Jorn Wildt <jw@...> wrote:

>
>
> --- In rest-discuss@yahoogroups.com <rest-discuss%40yahoogroups.com>,
> "wahbedahbe" <andrew.wahbe@...> wrote:
> > So when a media type is designed around a service rather than a type of
> client, I question if the result can be called REST. For example, a banking
> service that spits out a JSON format that simply serializes the account and
> transaction data structures used internally to represent the service's
> resources. i.e. if you aren't targeting a specific "type" of client by
> translating to that client's media type are you violating the constraints of
> REST?
>
> I keep comming back to this statement, you really got some thoughts
> starting. Thanks.
>
> It also puts some light on the problems of using a framework like WCF REST
> for a REST server: In WCF REST the default representation of an object is
> it's standard XML/JSON serialization. It is very easy to just serialize your
> internal Data-Transfer-Objects and let that be the representation. In this
> case you really design around your own service instead of your clients.
>
> /J�rn
>
>  __._,_.__
>

While I'm not a big fan of WCF, I think this has less to do with the tooling
and more to with connecting the dots between resources and representations
and understanding that all of these are for your clients and that how your
client(s) will use them should drive design decisions.  So if my client
wants the account and transaction data structures (as Andrew alludes too),
and that's what it's given, then I don't see what's necessarily wrong with
that.

Eb

Jim Webber wrote:
>  
> 
> Hey Eb,
> 
>  > I like this point. From a reach perspective, we should think more of the
>  > other agents/intermediaries that would have no clue on how to handle this
>  > media type (if they needed too). Regardless, the receiver (in a lot of
>  > cases) will need to understand the extensions to an existing media type.
> 
> If a client or intermediary doesn't understand a media type then all 
> bets are off - the client or intermediary doesn't understand the 
> service's contract.
> 
> Some clients know about lots of media types (e.g. browsers) some clients 
> know about few media types (e.g. Restbucks systems). That's the essence 
> of reach.

It's not just that they know or don't know, it's that every now and then 
an intermediary will block vnd content; this is not unusual in mobile 
networks.

Maybe this is like PUT/DELETE 5 years ago and it will come to pass that 
vnd types will be allowed to travel, I don't know. In the meantime the 
workaround is usually to use a generic media type like application/xml. 
I imagine there are implications to the notion of media types driving 
contracts when that is done - the test is whether changing the media 
type in HTTP to a generic type makes an actual difference (if not I 
imagine it's a point to point integration dressing up as REST).

My observation is that something like RDF could work better that custom 
media types at the cost of extra abstraction since RDF can readily 
support semantic information in the data that can drive a contract.

Bill

Bill,

 

can you point me to some references about proxies not allowing app/vnd.* ? It would be quite useful to get those scenarios documented if they're not already, and a summary search hasn't returned anything.

 

--

S
 
> To: jim@...
> CC: rest-discuss@yahoogroups.com
> From: bill@dehora.net
> Date: Fri, 15 Jan 2010 12:56:57 +0000
> Subject: Re: [rest-discuss] about rel and HATEOAS (theoretical question)
> 
> Jim Webber wrote:
> > 
> > 
> > Hey Eb,
> > 
> > > I like this point. From a reach perspective, we should think more of the
> > > other agents/intermediaries that would have no clue on how to handle this
> > > media type (if they needed too). Regardless, the receiver (in a lot of
> > > cases) will need to understand the extensions to an existing media type.
> > 
> > If a client or intermediary doesn't understand a media type then all 
> > bets are off - the client or intermediary doesn't understand the 
> > service's contract.
> > 
> > Some clients know about lots of media types (e.g. browsers) some clients 
> > know about few media types (e.g. Restbucks systems). That's the essence 
> > of reach.
> 
> It's not just that they know or don't know, it's that every now and then 
> an intermediary will block vnd content; this is not unusual in mobile 
> networks.
> 
> Maybe this is like PUT/DELETE 5 years ago and it will come to pass that 
> vnd types will be allowed to travel, I don't know. In the meantime the 
> workaround is usually to use a generic media type like application/xml. 
> I imagine there are implications to the notion of media types driving 
> contracts when that is done - the test is whether changing the media 
> type in HTTP to a generic type makes an actual difference (if not I 
> imagine it's a point to point integration dressing up as REST).
> 
> My observation is that something like RDF could work better that custom 
> media types at the cost of extra abstraction since RDF can readily 
> support semantic information in the data that can drive a contract.
> 
> Bill
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 
 		 	   		  
_________________________________________________________________
Got a cool Hotmail story? Tell us now
http://clk.atdmt.com/UKM/go/195013117/direct/01/

Recently, I've been thinking about how a coding framework or library
can influence the way developers implement applications. What would a
coding environment look like if it was meant to encourage results that
followed a particular _architectural_ style (not programming style).

IOW, is there a way to craft a framework that constrains developers in
ways that results in a REST-ful implementation of the application?

I did some digging, but have yet to find any writing on this topic.

Here are some "off-the-top-of-my-head" items:

For example, a framework might exhibit these REST-like traits:
- there is a clear separation of concerns between resource
identifiers, resources, and representations
- developers must define a resource as the public application interface
- the Uniform Interface is enforced (e.g. those methods are the only
public members exposed for a resource)
- developers must always associate one or more representation formats
with a resource and/or resource method before the implementation is
valid
- there is no way to define and use server-side session state objects

Some HTTP-specific traits might be:
- support for content negotiation is "baked-in"
- support for conditional requests is "baked-in" and automatic
- RPC-like implementation patterns (e.g. gateway URIs) are somehow
difficult to implement or are flagged as invalid

Any comments? Is this line of thinking pure folly? old hat? already
resolved sufficiently?

mca
http://amundsen.com/blog/

JAX-RS (Jersey) does a pretty good job IMO.  Python's Piston on Django
looks promising (...and that's the limit of my experience with REST
frameworks I've used in anger).

On Fri, Jan 15, 2010 at 12:27 PM, mike amundsen <mamund@...> wrote:
> Recently, I've been thinking about how a coding framework or library
> can influence the way developers implement applications. What would a
> coding environment look like if it was meant to encourage results that
> followed a particular _architectural_ style (not programming style).
>
> IOW, is there a way to craft a framework that constrains developers in
> ways that results in a REST-ful implementation of the application?
>
> I did some digging, but have yet to find any writing on this topic.
>
> Here are some "off-the-top-of-my-head" items:
>
> For example, a framework might exhibit these REST-like traits:
> - there is a clear separation of concerns between resource
> identifiers, resources, and representations
> - developers must define a resource as the public application interface
> - the Uniform Interface is enforced (e.g. those methods are the only
> public members exposed for a resource)
> - developers must always associate one or more representation formats
> with a resource and/or resource method before the implementation is
> valid
> - there is no way to define and use server-side session state objects
>
> Some HTTP-specific traits might be:
> - support for content negotiation is "baked-in"
> - support for conditional requests is "baked-in" and automatic
> - RPC-like implementation patterns (e.g. gateway URIs) are somehow
> difficult to implement or are flagged as invalid
>
> Any comments? Is this line of thinking pure folly? old hat? already
> resolved sufficiently?
>
> mca
> http://amundsen.com/blog/
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

Noah:

I am familiar w/ a handful of environments that are thought to be
HTTP/REST-friendly. I am wondering what it is about these frameworks
that give people reason to make that claim (true or false).

IOW, what are the abstract traits that make them so? Are these traits
shared across libraries/languages/platforms?

Maybe a way to start is to document the REST-ful features of each of
these libraries and draw conclusions.

mca
http://amundsen.com/blog/




On Fri, Jan 15, 2010 at 15:47, Noah Campbell <noahcampbell@gmail.com> wrote:
> JAX-RS (Jersey) does a pretty good job IMO. �Python's Piston on Django
> looks promising (...and that's the limit of my experience with REST
> frameworks I've used in anger).
>
> On Fri, Jan 15, 2010 at 12:27 PM, mike amundsen <mamund@...> wrote:
>> Recently, I've been thinking about how a coding framework or library
>> can influence the way developers implement applications. What would a
>> coding environment look like if it was meant to encourage results that
>> followed a particular _architectural_ style (not programming style).
>>
>> IOW, is there a way to craft a framework that constrains developers in
>> ways that results in a REST-ful implementation of the application?
>>
>> I did some digging, but have yet to find any writing on this topic.
>>
>> Here are some "off-the-top-of-my-head" items:
>>
>> For example, a framework might exhibit these REST-like traits:
>> - there is a clear separation of concerns between resource
>> identifiers, resources, and representations
>> - developers must define a resource as the public application interface
>> - the Uniform Interface is enforced (e.g. those methods are the only
>> public members exposed for a resource)
>> - developers must always associate one or more representation formats
>> with a resource and/or resource method before the implementation is
>> valid
>> - there is no way to define and use server-side session state objects
>>
>> Some HTTP-specific traits might be:
>> - support for content negotiation is "baked-in"
>> - support for conditional requests is "baked-in" and automatic
>> - RPC-like implementation patterns (e.g. gateway URIs) are somehow
>> difficult to implement or are flagged as invalid
>>
>> Any comments? Is this line of thinking pure folly? old hat? already
>> resolved sufficiently?
>>
>> mca
>> http://amundsen.com/blog/
>>
>>
>> ------------------------------------
>>
>> Yahoo! Groups Links
>>
>>
>>
>>
>

You might check out this post from Erik Wilde:

http://dret.typepad.com/dretblog/2009/05/rest-programming-toolbox-requirements.html

For me, the bare minimum includes:

- support for GET,PUT,POST, DELETE http methods (at least ... HEAD, OPTIONS
nice, too).
- for GET requests, I want to know what media type is preferred (combination
of looking at Accept header and/or file extension, etc.)
- for PUT/POST I want to be able to quickly and easily now the incoming
Content-type
- an easy way to parse the requested URL (w/ regex or named sections, etc.)
- the ability to dispatch to a handler function by any combination of the
above
- tools for creating representations in the most common media types: HTML (a
template language), JSON, Atom, RDF, etc. and serving the proper one based
on requested type.

In PHP, I don't think there is an obvious option (we've built our own
RESTful classes for Zend Framework: http://github.com/pkeane/cola-zend),
what I know of RoR seems to meet criteria, Django seems pretty nicely
RESTful, as does the Google App Engine "WebApp."

--peter

On Fri, Jan 15, 2010 at 2:27 PM, mike amundsen <mamund@...> wrote:

>
>
> Recently, I've been thinking about how a coding framework or library
> can influence the way developers implement applications. What would a
> coding environment look like if it was meant to encourage results that
> followed a particular _architectural_ style (not programming style).
>
> IOW, is there a way to craft a framework that constrains developers in
> ways that results in a REST-ful implementation of the application?
>
> I did some digging, but have yet to find any writing on this topic.
>
> Here are some "off-the-top-of-my-head" items:
>
> For example, a framework might exhibit these REST-like traits:
> - there is a clear separation of concerns between resource
> identifiers, resources, and representations
> - developers must define a resource as the public application interface
> - the Uniform Interface is enforced (e.g. those methods are the only
> public members exposed for a resource)
> - developers must always associate one or more representation formats
> with a resource and/or resource method before the implementation is
> valid
> - there is no way to define and use server-side session state objects
>
> Some HTTP-specific traits might be:
> - support for content negotiation is "baked-in"
> - support for conditional requests is "baked-in" and automatic
> - RPC-like implementation patterns (e.g. gateway URIs) are somehow
> difficult to implement or are flagged as invalid
>
> Any comments? Is this line of thinking pure folly? old hat? already
> resolved sufficiently?
>
> mca
> http://amundsen.com/blog/
>  
>

I know you know about it alread but...

 

OpenRasta enforces registration of resource URIs, resources and media types (through what we call codecs), and enforces an absolute separation between them.

 

OpenRasta is kind of a front-controller framework with http methods matching class methods on resource handlers, and separation from resources and the components that render them (codecs). Aka, multiple URIs may be available for one and only one resource, for which one or many handlers may return such resources, and one to many codecs may provide the various media types a resource supports

 

It also lets you do HTTP content-type and content-language negotiation out of the box, and charset negotiation in the next version.

 

Abeit, we don't do caching semantics yet, this is for the next version. I'm waiting for users to be coming back with scenarios so we can implement an API that makes sense to them, rather than one tailored only at being HTTP compliant (although of course that's also  a target).

 

--

S
 
> To: rest-discuss@yahoogroups.com
> From: mamund@...
> Date: Fri, 15 Jan 2010 15:27:20 -0500
> Subject: [rest-discuss] How can a framework/library encourage REST-ful development?
> 
> Recently, I've been thinking about how a coding framework or library
> can influence the way developers implement applications. What would a
> coding environment look like if it was meant to encourage results that
> followed a particular _architectural_ style (not programming style).
> 
> IOW, is there a way to craft a framework that constrains developers in
> ways that results in a REST-ful implementation of the application?
> 
> I did some digging, but have yet to find any writing on this topic.
> 
> Here are some "off-the-top-of-my-head" items:
> 
> For example, a framework might exhibit these REST-like traits:
> - there is a clear separation of concerns between resource
> identifiers, resources, and representations
> - developers must define a resource as the public application interface
> - the Uniform Interface is enforced (e.g. those methods are the only
> public members exposed for a resource)
> - developers must always associate one or more representation formats
> with a resource and/or resource method before the implementation is
> valid
> - there is no way to define and use server-side session state objects
> 
> Some HTTP-specific traits might be:
> - support for content negotiation is "baked-in"
> - support for conditional requests is "baked-in" and automatic
> - RPC-like implementation patterns (e.g. gateway URIs) are somehow
> difficult to implement or are flagged as invalid
> 
> Any comments? Is this line of thinking pure folly? old hat? already
> resolved sufficiently?
> 
> mca
> http://amundsen.com/blog/
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 
 		 	   		  
_________________________________________________________________
Tell us your greatest, weirdest and funniest Hotmail stories
http://clk.atdmt.com/UKM/go/195013117/direct/01/

Hi Peter,

Do you mind if we pick nits on this requirement?

"an easy way to parse the requested URL (w/ regex or named sections, etc.)"

I think the binding of a URL and the semantics of that URL to an
implementation should be discouraged.

Thoughts?

-Noah

On Fri, Jan 15, 2010 at 1:33 PM, Peter Keane <pkeane@...> wrote:

>
>
> You might check out this post from Erik Wilde:
>
>
> http://dret.typepad.com/dretblog/2009/05/rest-programming-toolbox-requirements.html
>
> For me, the bare minimum includes:
>
> - support for GET,PUT,POST, DELETE http methods (at least ... HEAD, OPTIONS
> nice, too).
> - for GET requests, I want to know what media type is preferred
> (combination of looking at Accept header and/or file extension, etc.)
> - for PUT/POST I want to be able to quickly and easily now the incoming
> Content-type
> - an easy way to parse the requested URL (w/ regex or named sections, etc.)
> - the ability to dispatch to a handler function by any combination of the
> above
> - tools for creating representations in the most common media types: HTML
> (a template language), JSON, Atom, RDF, etc. and serving the proper one
> based on requested type.
>
> In PHP, I don't think there is an obvious option (we've built our own
> RESTful classes for Zend Framework: http://github.com/pkeane/cola-zend),
> what I know of RoR seems to meet criteria, Django seems pretty nicely
> RESTful, as does the Google App Engine "WebApp."
>
> --peter
>
>
> On Fri, Jan 15, 2010 at 2:27 PM, mike amundsen <mamund@...> wrote:
>
>>
>>
>> Recently, I've been thinking about how a coding framework or library
>> can influence the way developers implement applications. What would a
>> coding environment look like if it was meant to encourage results that
>> followed a particular _architectural_ style (not programming style).
>>
>> IOW, is there a way to craft a framework that constrains developers in
>> ways that results in a REST-ful implementation of the application?
>>
>> I did some digging, but have yet to find any writing on this topic.
>>
>> Here are some "off-the-top-of-my-head" items:
>>
>> For example, a framework might exhibit these REST-like traits:
>> - there is a clear separation of concerns between resource
>> identifiers, resources, and representations
>> - developers must define a resource as the public application interface
>> - the Uniform Interface is enforced (e.g. those methods are the only
>> public members exposed for a resource)
>> - developers must always associate one or more representation formats
>> with a resource and/or resource method before the implementation is
>> valid
>> - there is no way to define and use server-side session state objects
>>
>> Some HTTP-specific traits might be:
>> - support for content negotiation is "baked-in"
>> - support for conditional requests is "baked-in" and automatic
>> - RPC-like implementation patterns (e.g. gateway URIs) are somehow
>> difficult to implement or are flagged as invalid
>>
>> Any comments? Is this line of thinking pure folly? old hat? already
>> resolved sufficiently?
>>
>> mca
>> http://amundsen.com/blog/
>>
>
>
>
> 

<snip>
You might check out this post from Erik Wilde:
</snip>
yep, i commented there already.

The list of features you provide are pretty close to those mentioned in a
few threads here and on the web.   Seems that many of these lists focus on
the day-to-day details of working with HTTP and being REST-ful along the
way. That's cool.

I need to do more thinking about _why_ these are listed in the context of
REST and what, if anything can be said about the style itself apart from the
protocol in use. I've found a handful of papers on matching software
architecture to programming, but nothing yet on _network_ architecture and
programming. I'm still digging.

mca
http://amundsen.com/blog/



On Fri, Jan 15, 2010 at 16:33, Peter Keane <pkeane@mail.utexas.edu> wrote:

> You might check out this post from Erik Wilde:
>
>
> http://dret.typepad.com/dretblog/2009/05/rest-programming-toolbox-requirements.html
>
> For me, the bare minimum includes:
>
> - support for GET,PUT,POST, DELETE http methods (at least ... HEAD, OPTIONS
> nice, too).
> - for GET requests, I want to know what media type is preferred
> (combination of looking at Accept header and/or file extension, etc.)
> - for PUT/POST I want to be able to quickly and easily now the incoming
> Content-type
> - an easy way to parse the requested URL (w/ regex or named sections, etc.)
> - the ability to dispatch to a handler function by any combination of the
> above
> - tools for creating representations in the most common media types: HTML
> (a template language), JSON, Atom, RDF, etc. and serving the proper one
> based on requested type.
>
> In PHP, I don't think there is an obvious option (we've built our own
> RESTful classes for Zend Framework: http://github.com/pkeane/cola-zend),
> what I know of RoR seems to meet criteria, Django seems pretty nicely
> RESTful, as does the Google App Engine "WebApp."
>
> --peter
>
> On Fri, Jan 15, 2010 at 2:27 PM, mike amundsen <mamund@...> wrote:
>
>>
>>
>> Recently, I've been thinking about how a coding framework or library
>> can influence the way developers implement applications. What would a
>> coding environment look like if it was meant to encourage results that
>> followed a particular _architectural_ style (not programming style).
>>
>> IOW, is there a way to craft a framework that constrains developers in
>> ways that results in a REST-ful implementation of the application?
>>
>> I did some digging, but have yet to find any writing on this topic.
>>
>> Here are some "off-the-top-of-my-head" items:
>>
>> For example, a framework might exhibit these REST-like traits:
>> - there is a clear separation of concerns between resource
>> identifiers, resources, and representations
>> - developers must define a resource as the public application interface
>> - the Uniform Interface is enforced (e.g. those methods are the only
>> public members exposed for a resource)
>> - developers must always associate one or more representation formats
>> with a resource and/or resource method before the implementation is
>> valid
>> - there is no way to define and use server-side session state objects
>>
>> Some HTTP-specific traits might be:
>> - support for content negotiation is "baked-in"
>> - support for conditional requests is "baked-in" and automatic
>> - RPC-like implementation patterns (e.g. gateway URIs) are somehow
>> difficult to implement or are flagged as invalid
>>
>> Any comments? Is this line of thinking pure folly? old hat? already
>> resolved sufficiently?
>>
>> mca
>> http://amundsen.com/blog/
>>  
>>
>
>

Thanks for the feedback on my initial thoughts about the REST style and
programming frameworks.

In order to explore this more w/o cluttering up this list, I started a
googlecode project/wiki [1] and related group [2]. I'd be happy to grant
anyone interested in participating contributor permissions to the project.
Just ping me offline (mamund AT yahoo DOT com) and I'll add you to the
project and group.

[1] http://code.google.com/p/implementing-rest/
[2] http://groups.google.com/group/implementing-rest

mca
http://amundsen.com/blog/



On Fri, Jan 15, 2010 at 16:48, mike amundsen <mamund@yahoo.com> wrote:

> <snip>
> You might check out this post from Erik Wilde:
> </snip>
> yep, i commented there already.
>
> The list of features you provide are pretty close to those mentioned in a
> few threads here and on the web.   Seems that many of these lists focus on
> the day-to-day details of working with HTTP and being REST-ful along the
> way. That's cool.
>
> I need to do more thinking about _why_ these are listed in the context of
> REST and what, if anything can be said about the style itself apart from the
> protocol in use. I've found a handful of papers on matching software
> architecture to programming, but nothing yet on _network_ architecture and
> programming. I'm still digging.
>
> mca
> http://amundsen.com/blog/
>
>
>
> On Fri, Jan 15, 2010 at 16:33, Peter Keane <pkeane@...> wrote:
>
>> You might check out this post from Erik Wilde:
>>
>>
>> http://dret.typepad.com/dretblog/2009/05/rest-programming-toolbox-requirements.html
>>
>> For me, the bare minimum includes:
>>
>> - support for GET,PUT,POST, DELETE http methods (at least ... HEAD,
>> OPTIONS nice, too).
>> - for GET requests, I want to know what media type is preferred
>> (combination of looking at Accept header and/or file extension, etc.)
>> - for PUT/POST I want to be able to quickly and easily now the incoming
>> Content-type
>> - an easy way to parse the requested URL (w/ regex or named sections,
>> etc.)
>> - the ability to dispatch to a handler function by any combination of the
>> above
>> - tools for creating representations in the most common media types: HTML
>> (a template language), JSON, Atom, RDF, etc. and serving the proper one
>> based on requested type.
>>
>> In PHP, I don't think there is an obvious option (we've built our own
>> RESTful classes for Zend Framework: http://github.com/pkeane/cola-zend),
>> what I know of RoR seems to meet criteria, Django seems pretty nicely
>> RESTful, as does the Google App Engine "WebApp."
>>
>> --peter
>>
>> On Fri, Jan 15, 2010 at 2:27 PM, mike amundsen <mamund@...> wrote:
>>
>>>
>>>
>>> Recently, I've been thinking about how a coding framework or library
>>> can influence the way developers implement applications. What would a
>>> coding environment look like if it was meant to encourage results that
>>> followed a particular _architectural_ style (not programming style).
>>>
>>> IOW, is there a way to craft a framework that constrains developers in
>>> ways that results in a REST-ful implementation of the application?
>>>
>>> I did some digging, but have yet to find any writing on this topic.
>>>
>>> Here are some "off-the-top-of-my-head" items:
>>>
>>> For example, a framework might exhibit these REST-like traits:
>>> - there is a clear separation of concerns between resource
>>> identifiers, resources, and representations
>>> - developers must define a resource as the public application interface
>>> - the Uniform Interface is enforced (e.g. those methods are the only
>>> public members exposed for a resource)
>>> - developers must always associate one or more representation formats
>>> with a resource and/or resource method before the implementation is
>>> valid
>>> - there is no way to define and use server-side session state objects
>>>
>>> Some HTTP-specific traits might be:
>>> - support for content negotiation is "baked-in"
>>> - support for conditional requests is "baked-in" and automatic
>>> - RPC-like implementation patterns (e.g. gateway URIs) are somehow
>>> difficult to implement or are flagged as invalid
>>>
>>> Any comments? Is this line of thinking pure folly? old hat? already
>>> resolved sufficiently?
>>>
>>> mca
>>> http://amundsen.com/blog/
>>>  
>>>
>>
>>
>

On Fri, Jan 15, 2010 at 3:45 PM, Noah Campbell <noahcampbell@...>wrote:

> Hi Peter,
>
> Do you mind if we pick nits on this requirement?
>
> "an easy way to parse the requested URL (w/ regex or named sections, etc.)"
>
> I think the binding of a URL and the semantics of that URL to an
> implementation should be discouraged.
>
> Thoughts?
>
>
Noah-

It's a valid point, and one that I have given some thought to.  Opaqueness
of the URL is valuable if/when is encourages use of HATEOS (and the myth
that REST == "pretty URLs" is hard but important to debunk).  I guess I'd
have to say that it depends on what you mean by "implementation" and how
leaky your implementation abstractions are.  I can imagine a nicely
abstracted system for which such "semantic" URLs could be quite appropriate
(as long as hypertext drives the application state in typical use of the web
app).  Here's a bit of wisdom from Roy F. on the matter:

http://tech.groups.yahoo.com/group/rest-discuss/message/3232

Either way, the server needs to do something useful w/ the URL and thus
needs way to "understand" it.

--peter


> -Noah
>
> On Fri, Jan 15, 2010 at 1:33 PM, Peter Keane <pkeane@...>wrote:
>
>>
>>
>> You might check out this post from Erik Wilde:
>>
>>
>> http://dret.typepad.com/dretblog/2009/05/rest-programming-toolbox-requirements.html
>>
>> For me, the bare minimum includes:
>>
>> - support for GET,PUT,POST, DELETE http methods (at least ... HEAD,
>> OPTIONS nice, too).
>> - for GET requests, I want to know what media type is preferred
>> (combination of looking at Accept header and/or file extension, etc.)
>> - for PUT/POST I want to be able to quickly and easily now the incoming
>> Content-type
>> - an easy way to parse the requested URL (w/ regex or named sections,
>> etc.)
>> - the ability to dispatch to a handler function by any combination of the
>> above
>> - tools for creating representations in the most common media types: HTML
>> (a template language), JSON, Atom, RDF, etc. and serving the proper one
>> based on requested type.
>>
>> In PHP, I don't think there is an obvious option (we've built our own
>> RESTful classes for Zend Framework: http://github.com/pkeane/cola-zend),
>> what I know of RoR seems to meet criteria, Django seems pretty nicely
>> RESTful, as does the Google App Engine "WebApp."
>>
>> --peter
>>
>>
>> On Fri, Jan 15, 2010 at 2:27 PM, mike amundsen <mamund@...> wrote:
>>
>>>
>>>
>>> Recently, I've been thinking about how a coding framework or library
>>> can influence the way developers implement applications. What would a
>>> coding environment look like if it was meant to encourage results that
>>> followed a particular _architectural_ style (not programming style).
>>>
>>> IOW, is there a way to craft a framework that constrains developers in
>>> ways that results in a REST-ful implementation of the application?
>>>
>>> I did some digging, but have yet to find any writing on this topic.
>>>
>>> Here are some "off-the-top-of-my-head" items:
>>>
>>> For example, a framework might exhibit these REST-like traits:
>>> - there is a clear separation of concerns between resource
>>> identifiers, resources, and representations
>>> - developers must define a resource as the public application interface
>>> - the Uniform Interface is enforced (e.g. those methods are the only
>>> public members exposed for a resource)
>>> - developers must always associate one or more representation formats
>>> with a resource and/or resource method before the implementation is
>>> valid
>>> - there is no way to define and use server-side session state objects
>>>
>>> Some HTTP-specific traits might be:
>>> - support for content negotiation is "baked-in"
>>> - support for conditional requests is "baked-in" and automatic
>>> - RPC-like implementation patterns (e.g. gateway URIs) are somehow
>>> difficult to implement or are flagged as invalid
>>>
>>> Any comments? Is this line of thinking pure folly? old hat? already
>>> resolved sufficiently?
>>>
>>> mca
>>> http://amundsen.com/blog/
>>>
>>
>>
>>
>> 
>
>
>

I wonder about the importance of opacity to all parties involved in the
request/response chain.

I can see why clients should assume opacity and I can see why intermediaries
should assume opacity. But is it important that the origin server treat the
URI as opaque?

mca
http://amundsen.com/blog/



On Fri, Jan 15, 2010 at 18:25, Peter Keane <pkeane@...> wrote:

>
>
> On Fri, Jan 15, 2010 at 3:45 PM, Noah Campbell <noahcampbell@...>wrote:
>
>> Hi Peter,
>>
>> Do you mind if we pick nits on this requirement?
>>
>> "an easy way to parse the requested URL (w/ regex or named sections,
>> etc.)"
>>
>> I think the binding of a URL and the semantics of that URL to an
>> implementation should be discouraged.
>>
>> Thoughts?
>>
>>
> Noah-
>
> It's a valid point, and one that I have given some thought to.  Opaqueness
> of the URL is valuable if/when is encourages use of HATEOS (and the myth
> that REST == "pretty URLs" is hard but important to debunk).  I guess I'd
> have to say that it depends on what you mean by "implementation" and how
> leaky your implementation abstractions are.  I can imagine a nicely
> abstracted system for which such "semantic" URLs could be quite appropriate
> (as long as hypertext drives the application state in typical use of the web
> app).  Here's a bit of wisdom from Roy F. on the matter:
>
> http://tech.groups.yahoo.com/group/rest-discuss/message/3232
>
> Either way, the server needs to do something useful w/ the URL and thus
> needs way to "understand" it.
>
> --peter
>
>
>> -Noah
>>
>>  On Fri, Jan 15, 2010 at 1:33 PM, Peter Keane <pkeane@...>wrote:
>>
>>>
>>>
>>> You might check out this post from Erik Wilde:
>>>
>>>
>>> http://dret.typepad.com/dretblog/2009/05/rest-programming-toolbox-requirements.html
>>>
>>> For me, the bare minimum includes:
>>>
>>> - support for GET,PUT,POST, DELETE http methods (at least ... HEAD,
>>> OPTIONS nice, too).
>>> - for GET requests, I want to know what media type is preferred
>>> (combination of looking at Accept header and/or file extension, etc.)
>>> - for PUT/POST I want to be able to quickly and easily now the incoming
>>> Content-type
>>> - an easy way to parse the requested URL (w/ regex or named sections,
>>> etc.)
>>> - the ability to dispatch to a handler function by any combination of the
>>> above
>>> - tools for creating representations in the most common media types: HTML
>>> (a template language), JSON, Atom, RDF, etc. and serving the proper one
>>> based on requested type.
>>>
>>> In PHP, I don't think there is an obvious option (we've built our own
>>> RESTful classes for Zend Framework: http://github.com/pkeane/cola-zend),
>>> what I know of RoR seems to meet criteria, Django seems pretty nicely
>>> RESTful, as does the Google App Engine "WebApp."
>>>
>>> --peter
>>>
>>>
>>> On Fri, Jan 15, 2010 at 2:27 PM, mike amundsen <mamund@...> wrote:
>>>
>>>>
>>>>
>>>> Recently, I've been thinking about how a coding framework or library
>>>> can influence the way developers implement applications. What would a
>>>> coding environment look like if it was meant to encourage results that
>>>> followed a particular _architectural_ style (not programming style).
>>>>
>>>> IOW, is there a way to craft a framework that constrains developers in
>>>> ways that results in a REST-ful implementation of the application?
>>>>
>>>> I did some digging, but have yet to find any writing on this topic.
>>>>
>>>> Here are some "off-the-top-of-my-head" items:
>>>>
>>>> For example, a framework might exhibit these REST-like traits:
>>>> - there is a clear separation of concerns between resource
>>>> identifiers, resources, and representations
>>>> - developers must define a resource as the public application interface
>>>> - the Uniform Interface is enforced (e.g. those methods are the only
>>>> public members exposed for a resource)
>>>> - developers must always associate one or more representation formats
>>>> with a resource and/or resource method before the implementation is
>>>> valid
>>>> - there is no way to define and use server-side session state objects
>>>>
>>>> Some HTTP-specific traits might be:
>>>> - support for content negotiation is "baked-in"
>>>> - support for conditional requests is "baked-in" and automatic
>>>> - RPC-like implementation patterns (e.g. gateway URIs) are somehow
>>>> difficult to implement or are flagged as invalid
>>>>
>>>> Any comments? Is this line of thinking pure folly? old hat? already
>>>> resolved sufficiently?
>>>>
>>>> mca
>>>> http://amundsen.com/blog/
>>>>
>>>
>>>
>>>
>>> 
>>
>>
>>
>

We [1] are trying to implement most of the things people metion around
here as being restful - where most of them find a consense, and
leaving some options where they dont, but picking one behavior as its
default.

From both Erik's post and Peter's message, it just partially supports
Atom/AtomPub so far, no RSS and RDF (language tag processing) out of
the box, but its coming:

http://restfulie.caelumobjects.com/restfulie_features

Are we in the right path?

[1] http://restfulie.caelumobjects.com

Regards




- support for GET,PUT,POST, DELETE http methods (at least ... HEAD,
OPTIONS nice, too).
- for GET requests, I want to know what media type is preferred
(combination of looking at Accept header and/or file extension, etc.)
- for PUT/POST I want to be able to quickly and easily now the
incoming Content-type
- an easy way to parse the requested URL (w/ regex or named sections, etc.)
- the ability to dispatch to a handler function by any combination of the above
- tools for creating representations in the most common media types:
HTML (a template language), JSON, Atom, RDF, etc. and serving the
proper one based on requested type.

On Jan 16, 2010, at 12:32 AM, mike amundsen wrote:

> I can see why clients should assume opacity and I can see why  
> intermediaries should assume opacity. But is it important that the  
> origin server treat the URI as opaque?

No, of course not. In fact - how would you implement a Web application  
without descting the URI to dispatch to the corresponding resource  
handler and to serve up the right representation?

Jan


--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

<snip>
In fact - how would you implement a Web application without descting
the URI to dispatch to the corresponding resource handler and to serve
up the right representation?
</snip>

And this is where I think some folks get confused. Since most folks
spend time building _servers_ they get used to the notion that the URI
is laden with important information, they focus on the importance of
constructing "pretty" URIs, etc. Then, when talking here about these
details, there is a wave of "oh, but URIs should be treated as
opaque", etc.

It is for this reason that, when I talk about URIs in the context of
REST/HTTP, I use the phrase "clients and intermediaries should treat
the URIs constructed by servers as opaque identifiers."

mca
http://amundsen.com/blog/




On Sat, Jan 16, 2010 at 06:31, Jan Algermissen <algermissen1971@...> wrote:
>
> On Jan 16, 2010, at 12:32 AM, mike amundsen wrote:
>
>> I can see why clients should assume opacity and I can see why
>> intermediaries should assume opacity. But is it important that the origin
>> server treat the URI as opaque?
>
> No, of course not. In fact - how would you implement a Web application
> without descting the URI to dispatch to the corresponding resource handler
> and to serve up the right representation?
>
> Jan
>
>
> --------------------------------------
> Jan Algermissen
>
> Mail: algermissen@...
> Blog: http://algermissen.blogspot.com/
> Home: http://www.jalgermissen.com
> --------------------------------------
>
>
>
>

I know, right!?!

Now, allowing intermediaries to break the opaqueness isn't a bad thing
and I wouldn't want to take that away, but the exercise of treating
URIs as opaque identifiers is helpful in understanding HATEOS.

-Noah

On Sat, Jan 16, 2010 at 3:31 AM, Jan Algermissen
<algermissen1971@...> wrote:
>
> On Jan 16, 2010, at 12:32 AM, mike amundsen wrote:
>
>> I can see why clients should assume opacity and I can see why
>> intermediaries should assume opacity. But is it important that the origin
>> server treat the URI as opaque?
>
> No, of course not. In fact - how would you implement a Web application
> without descting the URI to dispatch to the corresponding resource handler
> and to serve up the right representation?
>
> Jan
>
>
> --------------------------------------
> Jan Algermissen
>
> Mail: algermissen@...
> Blog: http://algermissen.blogspot.com/
> Home: http://www.jalgermissen.com
> --------------------------------------
>
>
>
>

Noah,

hmm - what is your point exactly?

On Jan 16, 2010, at 11:49 PM, Noah Campbell wrote:

> I know, right!?!
>
> Now, allowing intermediaries to break the opaqueness isn't a bad thing

Why do you think it is not a bad thing to introduce coupling between  
servers and intermediaries around the URI structure? Once you do that,  
the server looses control over its URI space.

> and I wouldn't want to take that away, but the exercise of treating
> URIs as opaque identifiers is helpful in understanding HATEOS.

Hmm - can it be you misunderstood what I said below? My sentence was  
targeted towards the 'But is it...' part.

Jan


>
> -Noah
>
> On Sat, Jan 16, 2010 at 3:31 AM, Jan Algermissen
> <algermissen1971@...> wrote:
>>
>> On Jan 16, 2010, at 12:32 AM, mike amundsen wrote:
>>
>>> I can see why clients should assume opacity and I can see why
>>> intermediaries should assume opacity. But is it important that the  
>>> origin
>>> server treat the URI as opaque?
>>
>> No, of course not. In fact - how would you implement a Web  
>> application
>> without descting the URI to dispatch to the corresponding resource  
>> handler
>> and to serve up the right representation?
>>
>> Jan
>>
>>
>> --------------------------------------
>> Jan Algermissen
>>
>> Mail: algermissen@...
>> Blog: http://algermissen.blogspot.com/
>> Home: http://www.jalgermissen.com
>> --------------------------------------
>>
>>
>>
>>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

Jan Algermissen wrote:
> Noah,
>
> hmm - what is your point exactly?
>
> On Jan 16, 2010, at 11:49 PM, Noah Campbell wrote:
>
>   
>> I know, right!?!
>>
>> Now, allowing intermediaries to break the opaqueness isn't a bad thing
>>     
>
> Why do you think it is not a bad thing to introduce coupling between  
> servers and intermediaries around the URI structure? Once you do that,  
> the server looses control over its URI space.
>
>   

Some types of reverse proxy mechanisms need to be configured against URI 
patterns though, no?

- Mike

I don't think it's a bad thing because intermediaries can leverage the
URI space that you've designed.  If you make it completely opaque then
how can you shape traffic based on the URL.

For example, splitting static content from application content using
the /app/... /static/... in your links can be exploited to make the
application scale.  I don't think this is outright wrong.


On Sat, Jan 16, 2010 at 4:20 PM, Jan Algermissen
<algermissen1971@mac.com> wrote:
> Noah,
>
> hmm - what is your point exactly?
>
> On Jan 16, 2010, at 11:49 PM, Noah Campbell wrote:
>
>> I know, right!?!
>>
>> Now, allowing intermediaries to break the opaqueness isn't a bad thing
>
> Why do you think it is not a bad thing to introduce coupling between servers
> and intermediaries around the URI structure? Once you do that, the server
> looses control over its URI space.
>
>> and I wouldn't want to take that away, but the exercise of treating
>> URIs as opaque identifiers is helpful in understanding HATEOS.
>
> Hmm - can it be you misunderstood what I said below? My sentence was
> targeted towards the 'But is it...' part.
>
> Jan
>
>
>>
>> -Noah
>>
>> On Sat, Jan 16, 2010 at 3:31 AM, Jan Algermissen
>> <algermissen1971@...> wrote:
>>>
>>> On Jan 16, 2010, at 12:32 AM, mike amundsen wrote:
>>>
>>>> I can see why clients should assume opacity and I can see why
>>>> intermediaries should assume opacity. But is it important that the
>>>> origin
>>>> server treat the URI as opaque?
>>>
>>> No, of course not. In fact - how would you implement a Web application
>>> without descting the URI to dispatch to the corresponding resource
>>> handler
>>> and to serve up the right representation?
>>>
>>> Jan
>>>
>>>
>>> --------------------------------------
>>> Jan Algermissen
>>>
>>> Mail: algermissen@acm.org
>>> Blog: http://algermissen.blogspot.com/
>>> Home: http://www.jalgermissen.com
>>> --------------------------------------
>>>
>>>
>>>
>>>
>>
>>
>> ------------------------------------
>>
>> Yahoo! Groups Links
>>
>>
>>
>
> --------------------------------------
> Jan Algermissen
>
> Mail: algermissen@...
> Blog: http://algermissen.blogspot.com/
> Home: http://www.jalgermissen.com
> --------------------------------------
>
>
>
>

where is a schema for the Atom APP ?

* I plan to marshal that in Java classes and then use it for
serializing  application/atomserv+xml types...



-- 
------------------------------------------
   Felipe Ga�cho
   10+ Java Programmer
   CEJUG Senior Advisor

On Jan 17, 2010, at 10:55 AM, Felipe Ga�cho wrote:

> where is a schema for the Atom APP ?

http://tools.ietf.org/html/rfc5023#section-8.3.1

Jan

>
> * I plan to marshal that in Java classes and then use it for
> serializing  application/atomserv+xml types...
>
>
>
> -- 
> ------------------------------------------
>   Felipe Ga�cho
>   10+ Java Programmer
>   CEJUG Senior Advisor
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

On Jan 17, 2010, at 2:28 AM, Noah Campbell wrote:

> I don't think it's a bad thing because intermediaries can leverage the
> URI space that you've designed.  If you make it completely opaque then
> how can you shape traffic based on the URL.

Yes, right. I thought of that after I hit 'send'.

However, the violation of the constraint becomes usually painfully  
visible when the reverse proxy and it's configuration is owned by a  
party different from that one owning the Web app. Sometimes you cannot  
change the Web app because you cannot immediately adjust the proxy  
config.

But the use case as such is indeed very common and often inevitable.  
Would be worthwhile to analyse what makes it so common and which  
variations of it exist. For example, the integration of static content  
(images etc.) and Web apps is a quite common use.


>
> For example, splitting static content from application content using
> the /app/... /static/... in your links can be exploited to make the
> application scale.  I don't think this is outright wrong.

Yes, agreed. I guess one aspect here is what part of the URI is being  
inspected. I guess it is less violating to inspect a general, more  
configuration level part as opposed to very specific ones such as  
looking for all product URIs with even product ID numbers.

There is a relation between how much of the URI is Web app controlled  
and how much is controlled by the app container configuration. Usually  
I'd expect the proxy config to touch those URI parts that are  
controlled by the container config.

Jan


>
>
> On Sat, Jan 16, 2010 at 4:20 PM, Jan Algermissen
> <algermissen1971@...> wrote:
>> Noah,
>>
>> hmm - what is your point exactly?
>>
>> On Jan 16, 2010, at 11:49 PM, Noah Campbell wrote:
>>
>>> I know, right!?!
>>>
>>> Now, allowing intermediaries to break the opaqueness isn't a bad  
>>> thing
>>
>> Why do you think it is not a bad thing to introduce coupling  
>> between servers
>> and intermediaries around the URI structure? Once you do that, the  
>> server
>> looses control over its URI space.
>>
>>> and I wouldn't want to take that away, but the exercise of treating
>>> URIs as opaque identifiers is helpful in understanding HATEOS.
>>
>> Hmm - can it be you misunderstood what I said below? My sentence was
>> targeted towards the 'But is it...' part.
>>
>> Jan
>>
>>
>>>
>>> -Noah
>>>
>>> On Sat, Jan 16, 2010 at 3:31 AM, Jan Algermissen
>>> <algermissen1971@...> wrote:
>>>>
>>>> On Jan 16, 2010, at 12:32 AM, mike amundsen wrote:
>>>>
>>>>> I can see why clients should assume opacity and I can see why
>>>>> intermediaries should assume opacity. But is it important that the
>>>>> origin
>>>>> server treat the URI as opaque?
>>>>
>>>> No, of course not. In fact - how would you implement a Web  
>>>> application
>>>> without descting the URI to dispatch to the corresponding resource
>>>> handler
>>>> and to serve up the right representation?
>>>>
>>>> Jan
>>>>
>>>>
>>>> --------------------------------------
>>>> Jan Algermissen
>>>>
>>>> Mail: algermissen@...
>>>> Blog: http://algermissen.blogspot.com/
>>>> Home: http://www.jalgermissen.com
>>>> --------------------------------------
>>>>
>>>>
>>>>
>>>>
>>>
>>>
>>> ------------------------------------
>>>
>>> Yahoo! Groups Links
>>>
>>>
>>>
>>
>> --------------------------------------
>> Jan Algermissen
>>
>> Mail: algermissen@...
>> Blog: http://algermissen.blogspot.com/
>> Home: http://www.jalgermissen.com
>> --------------------------------------
>>
>>
>>
>>

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

On Fri, Jan 15, 2010 at 3:27 PM, mike amundsen <mamund@...> wrote:

>
>
> Recently, I've been thinking about how a coding framework or library
> can influence the way developers implement applications. What would a
> coding environment look like if it was meant to encourage results that
> followed a particular _architectural_ style (not programming style).
>
> IOW, is there a way to craft a framework that constrains developers in
> ways that results in a REST-ful implementation of the application?
>
> I did some digging, but have yet to find any writing on this topic.
>
> Here are some "off-the-top-of-my-head" items:
>
> For example, a framework might exhibit these REST-like traits:
> - there is a clear separation of concerns between resource
> identifiers, resources, and representations
> - developers must define a resource as the public application interface
> - the Uniform Interface is enforced (e.g. those methods are the only
> public members exposed for a resource)
>

You seem to be equating resource with programming language object, but not
all languages are OO (and in fact I would argue the truly useful and
productive ones are not).

Any comments? Is this line of thinking pure folly? old hat? already
>
resolved sufficiently?
>

Perhaps take a look at webmachine, starting specifically with this page:

<http://bitbucket.org/justin/webmachine/wiki/WebmachineMechanics>

You can also read more by going to the top of the wiki there. Fundamentally
it's Alan Dean's HTTP diagram [1] in framework form.

--steve

[1] <http://webmachine.basho.com/diagram.html>

Steve:

<snip>
You seem to be equating resource with programming language object, but
not all languages are OO
</snip>

good point. thanks for the pointer to Webmachine.

I've added it to the list on the Project Wiki I started to track
frameworks w/ REST traits.
http://code.google.com/p/implementing-rest/wiki/RESTFrameworks

BTW - if anyone would like to suggest frameworks/content to add here,
send me an email off-list.

mca
http://amundsen.com/blog/




On Sun, Jan 17, 2010 at 02:36, Steve Vinoski <vinoski@...> wrote:
>
>
> On Fri, Jan 15, 2010 at 3:27 PM, mike amundsen <mamund@...> wrote:
>>
>>
>>
>> Recently, I've been thinking about how a coding framework or library
>> can influence the way developers implement applications. What would a
>> coding environment look like if it was meant to encourage results that
>> followed a particular _architectural_ style (not programming style).
>>
>> IOW, is there a way to craft a framework that constrains developers in
>> ways that results in a REST-ful implementation of the application?
>>
>> I did some digging, but have yet to find any writing on this topic.
>>
>> Here are some "off-the-top-of-my-head" items:
>>
>> For example, a framework might exhibit these REST-like traits:
>> - there is a clear separation of concerns between resource
>> identifiers, resources, and representations
>> - developers must define a resource as the public application interface
>> - the Uniform Interface is enforced (e.g. those methods are the only
>> public members exposed for a resource)
>
> You seem to be equating resource with programming language object, but not
> all languages are OO (and in fact I would argue the truly useful and
> productive ones are not).
>>
>> Any comments? Is this line of thinking pure folly? old hat? already
>>
>> resolved sufficiently?
>
> Perhaps take a look at webmachine, starting specifically with this page:
> <http://bitbucket.org/justin/webmachine/wiki/WebmachineMechanics>
> You can also read more by going to the top of the wiki there. Fundamentally
> it's Alan Dean's HTTP diagram [1] in framework form.
> --steve
> [1] <http://webmachine.basho.com/diagram.html>

I believe the expectation is that once a URI is made public it's
always out there.  If you want to move someone from an old URL you can
signal a 3xx redirect to the client.  You're not really tied to
another agency's configuration.

This behavior is more a property of HTTP than REST, but that's
probably another discussion.

-Noah

On Sun, Jan 17, 2010 at 4:16 AM, Jan Algermissen
<algermissen1971@...> wrote:
>
> On Jan 17, 2010, at 2:28 AM, Noah Campbell wrote:
>
>> I don't think it's a bad thing because intermediaries can leverage the
>> URI space that you've designed.  If you make it completely opaque then
>> how can you shape traffic based on the URL.
>
> Yes, right. I thought of that after I hit 'send'.
>
> However, the violation of the constraint becomes usually painfully visible
> when the reverse proxy and it's configuration is owned by a party different
> from that one owning the Web app. Sometimes you cannot change the Web app
> because you cannot immediately adjust the proxy config.
>
> But the use case as such is indeed very common and often inevitable. Would
> be worthwhile to analyse what makes it so common and which variations of it
> exist. For example, the integration of static content (images etc.) and Web
> apps is a quite common use.
>
>
>>
>> For example, splitting static content from application content using
>> the /app/... /static/... in your links can be exploited to make the
>> application scale.  I don't think this is outright wrong.
>
> Yes, agreed. I guess one aspect here is what part of the URI is being
> inspected. I guess it is less violating to inspect a general, more
> configuration level part as opposed to very specific ones such as looking
> for all product URIs with even product ID numbers.
>
> There is a relation between how much of the URI is Web app controlled and
> how much is controlled by the app container configuration. Usually I'd
> expect the proxy config to touch those URI parts that are controlled by the
> container config.
>
> Jan
>
>
>>
>>
>> On Sat, Jan 16, 2010 at 4:20 PM, Jan Algermissen
>> <algermissen1971@...> wrote:
>>>
>>> Noah,
>>>
>>> hmm - what is your point exactly?
>>>
>>> On Jan 16, 2010, at 11:49 PM, Noah Campbell wrote:
>>>
>>>> I know, right!?!
>>>>
>>>> Now, allowing intermediaries to break the opaqueness isn't a bad thing
>>>
>>> Why do you think it is not a bad thing to introduce coupling between
>>> servers
>>> and intermediaries around the URI structure? Once you do that, the server
>>> looses control over its URI space.
>>>
>>>> and I wouldn't want to take that away, but the exercise of treating
>>>> URIs as opaque identifiers is helpful in understanding HATEOS.
>>>
>>> Hmm - can it be you misunderstood what I said below? My sentence was
>>> targeted towards the 'But is it...' part.
>>>
>>> Jan
>>>
>>>
>>>>
>>>> -Noah
>>>>
>>>> On Sat, Jan 16, 2010 at 3:31 AM, Jan Algermissen
>>>> <algermissen1971@...> wrote:
>>>>>
>>>>> On Jan 16, 2010, at 12:32 AM, mike amundsen wrote:
>>>>>
>>>>>> I can see why clients should assume opacity and I can see why
>>>>>> intermediaries should assume opacity. But is it important that the
>>>>>> origin
>>>>>> server treat the URI as opaque?
>>>>>
>>>>> No, of course not. In fact - how would you implement a Web application
>>>>> without descting the URI to dispatch to the corresponding resource
>>>>> handler
>>>>> and to serve up the right representation?
>>>>>
>>>>> Jan
>>>>>
>>>>>
>>>>> --------------------------------------
>>>>> Jan Algermissen
>>>>>
>>>>> Mail: algermissen@...
>>>>> Blog: http://algermissen.blogspot.com/
>>>>> Home: http://www.jalgermissen.com
>>>>> --------------------------------------
>>>>>
>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>>> ------------------------------------
>>>>
>>>> Yahoo! Groups Links
>>>>
>>>>
>>>>
>>>
>>> --------------------------------------
>>> Jan Algermissen
>>>
>>> Mail: algermissen@...
>>> Blog: http://algermissen.blogspot.com/
>>> Home: http://www.jalgermissen.com
>>> --------------------------------------
>>>
>>>
>>>
>>>
>
> --------------------------------------
> Jan Algermissen
>
> Mail: algermissen@...
> Blog: http://algermissen.blogspot.com/
> Home: http://www.jalgermissen.com
> --------------------------------------
>
>
>
>

On Jan 17, 2010, at 7:14 PM, Noah Campbell wrote:

> I believe the expectation is that once a URI is made public it's
> always out there.

Yes. 'Cool URIs' are related to this issue.

To me it is bit disturbing that on the one hand, the server is  
supposed to be completely in charge of its own URI space while at the  
same time, it must sort of assume that once it publishes a URI it is  
likely to end up as a pointer in other systems and therefore should  
not change (or be redirected).


>  If you want to move someone from an old URL you can
> signal a 3xx redirect to the client.  You're not really tied to
> another agency's configuration.
>
> This behavior is more a property of HTTP than REST, but that's
> probably another discussion.
>

Yes (and likely a good one).

Jan



> -Noah
>
> On Sun, Jan 17, 2010 at 4:16 AM, Jan Algermissen
> <algermissen1971@...> wrote:
>>
>> On Jan 17, 2010, at 2:28 AM, Noah Campbell wrote:
>>
>>> I don't think it's a bad thing because intermediaries can leverage  
>>> the
>>> URI space that you've designed.  If you make it completely opaque  
>>> then
>>> how can you shape traffic based on the URL.
>>
>> Yes, right. I thought of that after I hit 'send'.
>>
>> However, the violation of the constraint becomes usually painfully  
>> visible
>> when the reverse proxy and it's configuration is owned by a party  
>> different
>> from that one owning the Web app. Sometimes you cannot change the  
>> Web app
>> because you cannot immediately adjust the proxy config.
>>
>> But the use case as such is indeed very common and often  
>> inevitable. Would
>> be worthwhile to analyse what makes it so common and which  
>> variations of it
>> exist. For example, the integration of static content (images etc.)  
>> and Web
>> apps is a quite common use.
>>
>>
>>>
>>> For example, splitting static content from application content using
>>> the /app/... /static/... in your links can be exploited to make the
>>> application scale.  I don't think this is outright wrong.
>>
>> Yes, agreed. I guess one aspect here is what part of the URI is being
>> inspected. I guess it is less violating to inspect a general, more
>> configuration level part as opposed to very specific ones such as  
>> looking
>> for all product URIs with even product ID numbers.
>>
>> There is a relation between how much of the URI is Web app  
>> controlled and
>> how much is controlled by the app container configuration. Usually  
>> I'd
>> expect the proxy config to touch those URI parts that are  
>> controlled by the
>> container config.
>>
>> Jan
>>
>>
>>>
>>>
>>> On Sat, Jan 16, 2010 at 4:20 PM, Jan Algermissen
>>> <algermissen1971@...> wrote:
>>>>
>>>> Noah,
>>>>
>>>> hmm - what is your point exactly?
>>>>
>>>> On Jan 16, 2010, at 11:49 PM, Noah Campbell wrote:
>>>>
>>>>> I know, right!?!
>>>>>
>>>>> Now, allowing intermediaries to break the opaqueness isn't a bad  
>>>>> thing
>>>>
>>>> Why do you think it is not a bad thing to introduce coupling  
>>>> between
>>>> servers
>>>> and intermediaries around the URI structure? Once you do that,  
>>>> the server
>>>> looses control over its URI space.
>>>>
>>>>> and I wouldn't want to take that away, but the exercise of  
>>>>> treating
>>>>> URIs as opaque identifiers is helpful in understanding HATEOS.
>>>>
>>>> Hmm - can it be you misunderstood what I said below? My sentence  
>>>> was
>>>> targeted towards the 'But is it...' part.
>>>>
>>>> Jan
>>>>
>>>>
>>>>>
>>>>> -Noah
>>>>>
>>>>> On Sat, Jan 16, 2010 at 3:31 AM, Jan Algermissen
>>>>> <algermissen1971@...> wrote:
>>>>>>
>>>>>> On Jan 16, 2010, at 12:32 AM, mike amundsen wrote:
>>>>>>
>>>>>>> I can see why clients should assume opacity and I can see why
>>>>>>> intermediaries should assume opacity. But is it important that  
>>>>>>> the
>>>>>>> origin
>>>>>>> server treat the URI as opaque?
>>>>>>
>>>>>> No, of course not. In fact - how would you implement a Web  
>>>>>> application
>>>>>> without descting the URI to dispatch to the corresponding  
>>>>>> resource
>>>>>> handler
>>>>>> and to serve up the right representation?
>>>>>>
>>>>>> Jan
>>>>>>
>>>>>>
>>>>>> --------------------------------------
>>>>>> Jan Algermissen
>>>>>>
>>>>>> Mail: algermissen@...
>>>>>> Blog: http://algermissen.blogspot.com/
>>>>>> Home: http://www.jalgermissen.com
>>>>>> --------------------------------------
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>> ------------------------------------
>>>>>
>>>>> Yahoo! Groups Links
>>>>>
>>>>>
>>>>>
>>>>
>>>> --------------------------------------
>>>> Jan Algermissen
>>>>
>>>> Mail: algermissen@...
>>>> Blog: http://algermissen.blogspot.com/
>>>> Home: http://www.jalgermissen.com
>>>> --------------------------------------
>>>>
>>>>
>>>>
>>>>
>>
>> --------------------------------------
>> Jan Algermissen
>>
>> Mail: algermissen@...
>> Blog: http://algermissen.blogspot.com/
>> Home: http://www.jalgermissen.com
>> --------------------------------------
>>
>>
>>
>>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

2010/1/17 Jan Algermissen <algermissen1971@...>

>
>
>
> On Jan 17, 2010, at 10:55 AM, Felipe Gaúcho wrote:
>
> > where is a schema for the Atom APP ?
>
> http://tools.ietf.org/html/rfc5023#section-8.3.1
>
> Jan
>
>
> >
> > * I plan to marshal that in Java classes and then use it for
> > serializing application/atomserv+xml types...
> >
> >
>

You might want to take a look at the ROME project, specifically the Propono
library:

http://wiki.java.net/bin/view/Javawsxml/RomePropono

--peter



> >
> > --
> > ------------------------------------------
> > Felipe Gaúcho
> > 10+ Java Programmer
> > CEJUG Senior Advisor
> >
> >
> > ------------------------------------
> >
> > Yahoo! Groups Links
> >
> >
> >
>
> --------------------------------------
> Jan Algermissen
>
> Mail: algermissen@... <algermissen%40acm.org>
> Blog: http://algermissen.blogspot.com/
> Home: http://www.jalgermissen.com
> --------------------------------------
>
>  
>

Thanks.. yes, Abdera and Rome are always on the radar, but I am trying
something new here.. reading and writting the data directly in the database,
without intermediate frameworks ...

I got Atom Feed working fine now:
http://fgaucho.dyndns.org:8080/arena-http/atom

After Jfokus I will check if adopting the same approach with the atom app is
worthy, or if it is better just accept the traditional frameworks :)

* For general purposes, I believe Abdera is the  best choice, but for my
little pet project I will push this idea of database driven a bit more.. and
if I succeed on that, I come back here with the feedback...
* JAXB is not Relax NG friendly... so eventually it will be faster to
rewrite a schema for the Atom Pub than try to fix all errors during the xjc
compilation.. (or to copy the classes from Rome if it is pure Atom Pub)

thanks for all tips.

On Jan 17, 2010, at 10:25 PM, Felipe Ga�cho wrote:

> JAXB is not Relax NG friendly... so eventually it will be faster to  
> rewrite a schema for the Atom Pub

There are tools that generate XSD from Relax NG!

Do not have pointers; I am using Oxygen for such things (oxygenxml.org).
Jan


--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

2010/1/17 Jan Algermissen <algermissen1971@...>:
>
> On Jan 17, 2010, at 10:25 PM, Felipe Ga�cho wrote:
>
>> JAXB is not Relax NG friendly... so eventually it will be faster to
>> rewrite a schema for the Atom Pub
>
> There are tools that generate XSD from Relax NG!


Trang (<http://code.google.com/p/jing-trang/>) is one such tool.  It
has worked quite well for me.

Peter

Thanks Peter,

it sounds great.. I executed it here and it generated a set of schemas..

later I will check how useful they are :)




On Sun, Jan 17, 2010 at 10:43 PM, Peter Williams <pezra@...>wrote:

>
>
> 2010/1/17 Jan Algermissen <algermissen1971@...<algermissen1971%40mac.com>
> >:
>
> >
> > On Jan 17, 2010, at 10:25 PM, Felipe Ga�cho wrote:
> >
> >> JAXB is not Relax NG friendly... so eventually it will be faster to
> >> rewrite a schema for the Atom Pub
> >
> > There are tools that generate XSD from Relax NG!
>
> Trang (<http://code.google.com/p/jing-trang/>) is one such tool. It
> has worked quite well for me.
>
> Peter
>  
>



-- 
------------------------------------------
  Felipe Ga�cho
  10+ Java Programmer
  CEJUG Senior Advisor

On Sun, Jan 17, 2010 at 2:24 PM, Jan Algermissen <algermissen1971@...>wrote:

>
>
>
>  To me it is bit disturbing that on the one hand, the server is
> supposed to be completely in charge of its own URI space while at the
> same time, it must sort of assume that once it publishes a URI it is
> likely to end up as a pointer in other systems and therefore should
> not change (or be redirected).
>
>
>
Even within the constraints of the REST architectural style?

> Can you elaborate on the database scenario you plan to work on?

sure.. I will present it next week in Jfokus, a Java conference in
Stockholm, Sweden...

I am busy with the presentation slides .. but as soon I present my
work I will post here the link to the PDF and explain better what I am
doing..

basically, I am modeling Atom in the relational database, and using
annotations to traverse data directly from the HTTP interface and the
persistence layer, without transformations or copies in the middle of
the way....

On Jan 18, 2010, at 4:37 AM, Eb wrote:

>
>
> On Sun, Jan 17, 2010 at 2:24 PM, Jan Algermissen <algermissen1971@... 
> > wrote:
>
>
>
> To me it is bit disturbing that on the one hand, the server is
> supposed to be completely in charge of its own URI space while at the
> same time, it must sort of assume that once it publishes a URI it is
> likely to end up as a pointer in other systems and therefore should
> not change (or be redirected).
>
>
>
> Even within the constraints of the REST architectural style?

Yes, I think so. Though it seems to conradict the client server  
decoupling objective.

An interesting question would be what criteria to use to differentate  
between URIs that make good bookmarks and those that don't.

Jan




--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

--- In rest-discuss@yahoogroups.com, Noah Campbell <noahcampbell@...> wrote:
>
> JAX-RS (Jersey) does a pretty good job IMO.  Python's Piston on Django
> looks promising (...and that's the limit of my experience with REST
> frameworks I've used in anger).
> 


Sorry, but I don't understand comments like this.  I'm sure you meant well, so I hope you won't mind me demanding more rigor.

You're not contributing any insight or answering the OP's question.  Instead, you are dropping names.

Could you please elaborate with a short discussion of how the design of Jersey encourages an architectural style?  Ditto for Piston.

Otherwise, again, I see it as mere namedropping.

Especially as you apparently have experience with "REST frameworks" you dislike, you should be able to form a qualitative if not quantitative analysis of what makes them good or bad.

--- In rest-discuss@yahoogroups.com, Peter Keane <pkeane@...> wrote:
>
> You might check out this post from Erik Wilde:
> 
> http://dret.typepad.com/dretblog/2009/05/rest-programming-toolbox-requirements.html
> 
> For me, the bare minimum includes:
> 
> - support for GET,PUT,POST, DELETE http methods (at least ... HEAD, OPTIONS
> nice, too).
> - for GET requests, I want to know what media type is preferred (combination
> of looking at Accept header and/or file extension, etc.)
> - for PUT/POST I want to be able to quickly and easily now the incoming
> Content-type
> - an easy way to parse the requested URL (w/ regex or named sections, etc.)
> - the ability to dispatch to a handler function by any combination of the
> above
> - tools for creating representations in the most common media types: HTML (a
> template language), JSON, Atom, RDF, etc. and serving the proper one based
> on requested type.
> 
> In PHP, I don't think there is an obvious option (we've built our own
> RESTful classes for Zend Framework: http://github.com/pkeane/cola-zend),
> what I know of RoR seems to meet criteria, Django seems pretty nicely
> RESTful, as does the Google App Engine "WebApp."
> 
> --peter
> 


I think you are conflating too many things here.

First, you are conflating low-level plumbing with higher-level concepts.

Second, since REST is about information resources, any API that doesn't have a strategy for automatically destroying resources after invalid operations, is useless, stupid, and ugly.  This is higher-level than garbage collected memory management.

Stuff like URI parsing seems silly to me to consider as on the same level as those other concerns.  The author is monolithically treating the problem; he is not designing a media type. Instead, he is exposing the entire statespace of a session to the programmer.  How do you impose semantics on that???

Again, Real-time Object-Oriented programming is helpful here, despite what some on this list have countered to saying (by attacking me unfairly by saying I was attempting to re-create "distributed objects", rather than using real math to back up their arguments, or rather than simply using anything more than attacking with buzzwords to justify their position).  Modeling communication in a distributed system using composable Input/Output Automata sequences is a proven technique.  State machines can thus radically simplify the design of any system.  Realizing that in a truly object-oriented system, built from abstract data objects (ADOs), you cannot have any notion of history, allows you to more modularly solve problems.

In short, yes, you can use the stuff listed above, but don't think it is as simple as AND-join'ing all those properties together and you get REST.  That's just dumb and silly.

Used in anger means I've used these frameworks beyond the superficial
hello world example.  I actually like both.  I can definitely see how
my comment would be misinterpreted.

-Noah

On Mon, Jan 18, 2010 at 9:57 AM, johnzabroski <johnzabroski@...> wrote:
>
>
> --- In rest-discuss@yahoogroups.com, Noah Campbell <noahcampbell@...> wrote:
>>
>> JAX-RS (Jersey) does a pretty good job IMO.  Python's Piston on Django
>> looks promising (...and that's the limit of my experience with REST
>> frameworks I've used in anger).
>>
>
>
> Sorry, but I don't understand comments like this.  I'm sure you meant well, so I hope you won't mind me demanding more rigor.
>
> You're not contributing any insight or answering the OP's question.  Instead, you are dropping names.
>
> Could you please elaborate with a short discussion of how the design of Jersey encourages an architectural style?  Ditto for Piston.
>
> Otherwise, again, I see it as mere namedropping.
>
> Especially as you apparently have experience with "REST frameworks" you dislike, you should be able to form a qualitative if not quantitative analysis of what makes them good or bad.
>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

 > Atom has reach because lots of systems out there already
 > understand how to process it.
 > application/vnd.restbucks+xml does not have reach
 > because there aren't
 > many systems out there that understand it.

There's an angle on this worth mentioning, which is that Atom has reach 
because it can aggregate other content either as extensions, mapping, or 
enveloping.

I find it very common that people don't design data formats with 
aggregation in mind, instead investing in very specific ("rich!") formats.

So you get lots of this

<cup />
<barrista />
<order />

and sometimes you get this

  <orders>
   <order/>

but most people don't plan for this

  <list>
   <order />
   <cup />

which leaves out a whole class of serendipity ("usecases!"). I guess the 
same thing goes for business semantics, people mostly code things up as 
business logic ("dsls!") instead of relying on generic techniques.

Bill



Jim Webber wrote:
>  
> 
> Hi Eb,
> 
>  > Why would this make a difference? We keep talking about reach, but 
> most (if
>  > not all?) media types were designed for a specific client.
> 
> Or clients. Atom has reach because lots of systems out there already 
> understand how to process it.
> 
> application/vnd.restbucks+xml does not have reach because there aren't 
> many systems out there that understand it. Nor are there lots of 
> libraries to choose from on lots of platforms that implement the 
> processing model for that type. But it does have the advantage that it 
> works really well for coffee ordering within the Restbucks domain.
> 
> Jim
> 
> 

Hi,

I've been writing my app using a Java Swing client, and a server. The 
client asks for data in JSON-format from the server using a RESTful URL 
structure, and present it in the UI. All is well.

Now I'm facing the problem of figuring out what the user is allowed to 
do with the data, both based on security (=does the user have the 
correct role) and state (=is an action valid given the state). With an 
HTML client this would be easy, since then the HTML could change 
depending on these things. In my situation, where the client just gets 
JSON-data, it seems to me that I have to extend my usage of JSON so that 
I can get both the data to view, and a list of what actions the client 
is allowed to perform, and then enable/disable UI elements accordingly.

Something like this would be sent from the server:
{"commands":["cmd1","cmd2],"data":{"foo":"bar"}}

With the above I can both get the data I need to show, and know what the 
user is allowed to do with it.

Has anyone done this? Or should I skip directly to XHTML instead and use 
<a>'s to let the client know what it can do? And if so, how would the 
data be best transferred (key/value data)?

Any tips would be appreciated!

/Rickard

On Jan 19, 2010, at 12:51 PM, Rickard �berg wrote:

> Hi,
>
> I've been writing my app using a Java Swing client, and a server. The
> client asks for data in JSON-format from the server using a RESTful  
> URL
> structure, and present it in the UI. All is well.

What do you mean by "RESTful URL structure"?

>
> Now I'm facing the problem of figuring out what the user is allowed to
> do with the data, both based on security (=does the user have the
> correct role) and state (=is an action valid given the state). With an
> HTML client this would be easy, since then the HTML could change
> depending on these things.

The JSON can simply change as well based on the provilidges the user  
has.

> In my situation, where the client just gets
> JSON-data, it seems to me that I have to extend my usage of JSON so  
> that
> I can get both the data to view, and a list of what actions the client
> is allowed to perform, and then enable/disable UI elements  
> accordingly.

You should include Authentication information with the request and  
determine on that basis what JSON to return. The JSON should drive the  
UI with regard to the available actions (==next possible transitions  
in the application by the user through your UI).

>
> Something like this would be sent from the server:
> {"commands":["cmd1","cmd2],"data":{"foo":"bar"}}

Well, maybe - if you think of 'cmd' in terms of 'next transition'. If  
you UI reacts on the cmds received that would be good.

>
> With the above I can both get the data I need to show, and know what  
> the
> user is allowed to do with it.

I think that is ok, if you context prevents simpler solutions (e.g.  
use HTML+browser in the first place).


>
> Has anyone done this? Or should I skip directly to XHTML instead and  
> use
> <a>'s to let the client know what it can do? And if so, how would the
> data be best transferred (key/value data)?

Why did you not create an HTML based UI?

Jan


>
> Any tips would be appreciated!
>
> /Rickard
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

On Tue, Jan 19, 2010 at 6:16 AM, Bill de hOra <bill@...> wrote:

>  > Atom has reach because lots of systems out there already
>  > understand how to process it.
>  > application/vnd.restbucks+xml does not have reach
>  > because there aren't
>  > many systems out there that understand it.
>
> There's an angle on this worth mentioning, which is that Atom has reach
> because it can aggregate other content either as extensions, mapping, or
> enveloping.
>
> I find it very common that people don't design data formats with
> aggregation in mind, instead investing in very specific ("rich!") formats.
>
> So you get lots of this
>
> <cup />
> <barrista />
> <order />
>
> and sometimes you get this
>
>  <orders>
>   <order/>
>
> but most people don't plan for this
>
>  <list>
>   <order />
>   <cup />
>
> which leaves out a whole class of serendipity ("usecases!"). I guess the
> same thing goes for business semantics, people mostly code things up as
> business logic ("dsls!") instead of relying on generic techniques.
>
> Bill
>
>
>
Bill -

I'm not sure I get your point here.  What do you mean by "reach"?

Thanks.

Eb

On 2010-01-19 13.05, Jan Algermissen wrote:
>> I've been writing my app using a Java Swing client, and a server. The
>> client asks for data in JSON-format from the server using a RESTful URL
>> structure, and present it in the UI. All is well.
>
> What do you mean by "RESTful URL structure"?

A URL structure that represents resources that can return state and 
perform actions on them.

>> In my situation, where the client just gets
>> JSON-data, it seems to me that I have to extend my usage of JSON so that
>> I can get both the data to view, and a list of what actions the client
>> is allowed to perform, and then enable/disable UI elements accordingly.
>
> You should include Authentication information with the request and
> determine on that basis what JSON to return. The JSON should drive the
> UI with regard to the available actions (==next possible transitions in
> the application by the user through your UI).

That was the idea. I was just curious how others have formatted their 
JSON (if anyone has done it at all) to include such action info.

>> Something like this would be sent from the server:
>> {"commands":["cmd1","cmd2],"data":{"foo":"bar"}}
>
> Well, maybe - if you think of 'cmd' in terms of 'next transition'. If
> you UI reacts on the cmds received that would be good.

That's the idea. We could also replace "cmd1" with URL's instead, so 
that the client doesn't have to generate URL's, but then we need more 
info to be sent, similar to <a>'s (rel+href attributes).

>> With the above I can both get the data I need to show, and know what the
>> user is allowed to do with it.
>
> I think that is ok, if you context prevents simpler solutions (e.g. use
> HTML+browser in the first place).

Yeah, that is not an option. We need the more powerful UI features of 
Swing, and also want to be able to connect to several servers at once in 
the UI.

/Rickard

> On 2010-01-19 13.05, Jan Algermissen wrote:
> >> I've been writing my app using a Java Swing client, and a server. 
> The
> >> client asks for data in JSON-format from the server using a 
> RESTful URL
> >> structure, and present it in the UI. All is well.
> >
> > What do you mean by "RESTful URL structure"?
>
> A URL structure that represents resources that can return state and
> perform actions on them.
>
> >> In my situation, where the client just gets
> >> JSON-data, it seems to me that I have to extend my usage of JSON 
> so that
> >> I can get both the data to view, and a list of what actions the 
> client
> >> is allowed to perform, and then enable/disable UI elements 
> accordingly.
> >
> > You should include Authentication information with the request and
> > determine on that basis what JSON to return. The JSON should drive 
> the
> > UI with regard to the available actions (==next possible 
> transitions in
> > the application by the user through your UI).
>
> That was the idea. I was just curious how others have formatted their
> JSON (if anyone has done it at all) to include such action info.
>
> >> Something like this would be sent from the server:
> >> {"commands":["cmd1","cmd2],"data":{"foo":"bar"}}
> >
> > Well, maybe - if you think of 'cmd' in terms of 'next transition'. 
> If
> > you UI reacts on the cmds received that would be good.
>
> That's the idea. We could also replace "cmd1" with URL's instead, so
> that the client doesn't have to generate URL's, but then we need more
> info to be sent, similar to <a>'s (rel+href attributes).
>
> >> With the above I can both get the data I need to show, and know 
> what the
> >> user is allowed to do with it.
> >
> > I think that is ok, if you context prevents simpler solutions 
> (e.g. use
> > HTML+browser in the first place).
>
> Yeah, that is not an option. We need the more powerful UI features of
> Swing, and also want to be able to connect to several servers at 
> once in
> the UI.
>
hi Richard,

You could go a firefox plugin (or similar) - that'll get you round the 
'several servers at once' issue, but, doesn't help with the lack of 
powerful UI features - although nowadays I find that many of the 
things which the browser environment enables - and easily too! - make 
it better than swing ...

Roger

>
> /Rickard
>
> 




______________________________________________________________________
                                       
 Fujitsu Laboratories of Europe Limited
 Hayes Park Central, Hayes End Road, Hayes, Middlesex, UB4 8FE
 Registered No. 4153469

 This e-mail and any attachments are for the sole use of addressee(s) and
 may contain information which is privileged and confidential. Unauthorised
 use or copying for disclosure is strictly prohibited. The fact that this
 e-mail has been scanned by Trendmicro Interscan and McAfee Groupshield does
 not guarantee that it has not been intercepted or amended nor that it is
 virus-free.

Eb wrote:
>
>
>
> On Tue, Jan 19, 2010 at 6:16 AM, Bill de hOra <bill@... 
> <mailto:bill@...>> wrote:
>
>      > Atom has reach because lots of systems out there already
>      > understand how to process it.
>      > application/vnd.restbucks+xml does not have reach
>      > because there aren't
>      > many systems out there that understand it.
>
>     There's an angle on this worth mentioning, which is that Atom has
>     reach
>     because it can aggregate other content either as extensions,
>     mapping, or
>     enveloping.
>
>     I find it very common that people don't design data formats with
>     aggregation in mind, instead investing in very specific ("rich!")
>     formats.
>
>     So you get lots of this
>
>     <cup />
>     <barrista />
>     <order />
>
>     and sometimes you get this
>
>      <orders>
>       <order/>
>
>     but most people don't plan for this
>
>      <list>
>       <order />
>       <cup />
>
>     which leaves out a whole class of serendipity ("usecases!"). I
>     guess the
>     same thing goes for business semantics, people mostly code things
>     up as
>     business logic ("dsls!") instead of relying on generic techniques.
>
>     Bill
>
>
>
> Bill -
>
> I'm not sure I get your point here.  What do you mean by "reach"?
>
> Thanks.
>
> Eb

Essentially just the amount of clients that understand the media type.

I tend to look at it in terms of concentration/dilution - i.e. custom 
media types are more 'concentrated', in that they have stronger meaning 
but to a smaller spread of clients. An equally generic media types are 
more dilute, in that they have weaker meaning but to a larger spread of 
clients.

Where you draw the line should depend on how wide a particular 
application is intended to be distributed - extending atom is an example 
of a good opportunity for compromise.

- Mike

On Jan 19, 2010, at 1:25 PM, Rickard �berg wrote:

> On 2010-01-19 13.05, Jan Algermissen wrote:
>>> I've been writing my app using a Java Swing client, and a server.  
>>> The
>>> client asks for data in JSON-format from the server using a  
>>> RESTful URL
>>> structure, and present it in the UI. All is well.
>>
>> What do you mean by "RESTful URL structure"?
>
> A URL structure that represents resources that can return state and  
> perform actions on them.

Hmm - but any URL represents a resource by definition and resources  
hold state. I wonder why you even mentioned it. What kind of actions  
do you think of?

> [...]

>>> Something like this would be sent from the server:
>>> {"commands":["cmd1","cmd2],"data":{"foo":"bar"}}
>>
>> Well, maybe - if you think of 'cmd' in terms of 'next transition'. If
>> you UI reacts on the cmds received that would be good.
>
> That's the idea. We could also replace "cmd1" with URL's instead, so  
> that the client doesn't have to generate URL's, but then we need  
> more info to be sent, similar to <a>'s (rel+href attributes).

What do you mean by 'generate URLs'? The client should not do this  
(only on the basis of a form or template it receives) because it  
introduces coupling on out-of-band information (the knowledge of the  
desired URI structure). If you use REST, use it all the way through.  
The 'more info to be sent' is the price you pay for the decreased  
coupling.


>
>>> With the above I can both get the data I need to show, and know  
>>> what the
>>> user is allowed to do with it.
>>
>> I think that is ok, if you context prevents simpler solutions (e.g.  
>> use
>> HTML+browser in the first place).
>
> Yeah, that is not an option. We need the more powerful UI features  
> of Swing, and also want to be able to connect to several servers at  
> once in the UI.

Ok, see the point.

Jan




>
> /Rickard

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

On Tue, Jan 19, 2010 at 7:37 AM, Mike Kelly <mike@...> wrote:

> Essentially just the amount of clients that understand the media type.
>
> I tend to look at it in terms of concentration/dilution - i.e. custom media
> types are more 'concentrated', in that they have stronger meaning but to a
> smaller spread of clients. An equally generic media types are more dilute,
> in that they have weaker meaning but to a larger spread of clients.
>
> Where you draw the line should depend on how wide a particular application
> is intended to be distributed - extending atom is an example of a good
> opportunity for compromise.
>
> - Mike
>

Ok, I buy that more clients will "accept" (potentially) the media type, but
that doesn't really mean they understand it (from a "get stuff done"
perspective), if the media type has been extended to now include semantics
not defined into the original specification of the media type.  The client
will just see junk.  Maybe "reach" is the wrong word to define what we're
trying to describe here because I find it very misleading (personally).

On Tue, Jan 19, 2010 at 7:25 AM, Rickard �berg <rickardoberg@...>wrote:

>
>
> That's the idea. We could also replace "cmd1" with URL's instead, so
> that the client doesn't have to generate URL's, but then we need more
> info to be sent, similar to <a>'s (rel+href attributes).
>
>
>
Introduce your own linking structure in the json representation.  Nothing is
really stopping you from returning html-like or atom-like attributes in your
json. (At least I don't think so.).

On Jan 19, 2010, at 12:51 PM, Rickard �berg wrote:

> Hi,
>
> I've been writing my app using a Java Swing client, and a server.


Are you implementing a program on the client side that has a GUI and  
happens to asks several service for some data or are you implementing  
a browser that is supposed to be entirely driven by the  
representations it receives and just happens to hav a Swing GIU?

Jan


> The
> client asks for data in JSON-format from the server using a RESTful  
> URL
> structure, and present it in the UI. All is well.
>
> Now I'm facing the problem of figuring out what the user is allowed to
> do with the data, both based on security (=does the user have the
> correct role) and state (=is an action valid given the state). With an
> HTML client this would be easy, since then the HTML could change
> depending on these things. In my situation, where the client just gets
> JSON-data, it seems to me that I have to extend my usage of JSON so  
> that
> I can get both the data to view, and a list of what actions the client
> is allowed to perform, and then enable/disable UI elements  
> accordingly.
>
> Something like this would be sent from the server:
> {"commands":["cmd1","cmd2],"data":{"foo":"bar"}}
>
> With the above I can both get the data I need to show, and know what  
> the
> user is allowed to do with it.
>
> Has anyone done this? Or should I skip directly to XHTML instead and  
> use
> <a>'s to let the client know what it can do? And if so, how would the
> data be best transferred (key/value data)?
>
> Any tips would be appreciated!
>
> /Rickard
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

"Eb wrote:
>
>
>
>
> On Tue, Jan 19, 2010 at 7:37 AM, Mike Kelly <mike@... 
> <mailto:mike@...>> wrote:
>
>     Essentially just the amount of clients that understand the media type.
>
>     I tend to look at it in terms of concentration/dilution - i.e.
>     custom media types are more 'concentrated', in that they have
>     stronger meaning but to a smaller spread of clients. An equally
>     generic media types are more dilute, in that they have weaker
>     meaning but to a larger spread of clients.
>
>     Where you draw the line should depend on how wide a particular
>     application is intended to be distributed - extending atom is an
>     example of a good opportunity for compromise.
>
>     - Mike
>
>
> Ok, I buy that more clients will "accept" (potentially) the media 
> type, but that doesn't really mean they understand it (from a "get 
> stuff done" perspective), if the media type has been extended to now 
> include semantics not defined into the original specification of the 
> media type.  The client will just see junk.  Maybe "reach" is the 
> wrong word to define what we're trying to describe here because I find 
> it very misleading (personally).
>

Your concerns point to the essence of the 'reach' concept - the idea 
that as you add custom semantics, the amount of clients able to 
understand decreases i.e. you are "reaching" less clients.

Extending atom - 'basic' atom clients will see the standard atom and 
your extra junk, rather than 'just junk'. That is why you would choose 
to extend, rather than start from scratch.

I don't find "reach" massively misleading - what about that terminology 
causes the problem?

http://www.google.com/search?q=define:+reach

" be in or establish communication with; "Our advertisements reach 
millions""

" to extend as far as; "The sunlight reached the wall"; "Can he reach?" 
"The chair must not touch the wall"

Cheers,
Mike

On 2010-01-19 14.01, Jan Algermissen wrote:
>> I've been writing my app using a Java Swing client, and a server.
>
> Are you implementing a program on the client side that has a GUI and
> happens to asks several service for some data or are you implementing a
> browser that is supposed to be entirely driven by the representations it
> receives and just happens to hav a Swing GIU?

The first. There's no generalness at all about it; the client is 
entirely coupled to my server, with regard to what to expect. The client 
is delivered using Java WebStart, so I also know that the client and 
server expectations always match.

/Rickard

When representing links in JSON, mirroring the Atom "link" element works well:

{
  "link" :
  {
     "rel" : "alternate",
     "href" : "http://east-nj1.photos.example.org/987/nj1-1234",
   }
}

OR

{
"links" :
  [
    {
      "rel" : "alternate",
      "href" : "http://east-nj1.photos.example.org/987/nj1-1234"
    },
    {
      "rel" : "http://www.example.org/rels/owner",
      "href" : "http://east-nj1.photos.example.org/987",
    }
  ]
}

When sending a representation of the resource to the client, only
include the link elements that are valid at that time. The links
themselves, along with documented "rel" values, should be sufficient
to allow the client state engine to locate and interpret the available
state transitions (actions) for that representation.

You may also find that you also need to mimic the XHTML FORM element
in order to communicate to the client what data elements are valid
when sending a representation back to the server. Finally, you may
need to be able to communicate "embed" links that tell the client to
fetch the resource representation and render it in place (think IMG
tag) instead of treat the link as a navigation (A tag).

This all starts to sound a lot like creating a MIME media-type based
on the JSON data format, eh<g>?

mca
http://amundsen.com/blog/




On Tue, Jan 19, 2010 at 06:51, Rickard �berg <rickardoberg@...> wrote:
> Hi,
>
> I've been writing my app using a Java Swing client, and a server. The
> client asks for data in JSON-format from the server using a RESTful URL
> structure, and present it in the UI. All is well.
>
> Now I'm facing the problem of figuring out what the user is allowed to
> do with the data, both based on security (=does the user have the
> correct role) and state (=is an action valid given the state). With an
> HTML client this would be easy, since then the HTML could change
> depending on these things. In my situation, where the client just gets
> JSON-data, it seems to me that I have to extend my usage of JSON so that
> I can get both the data to view, and a list of what actions the client
> is allowed to perform, and then enable/disable UI elements accordingly.
>
> Something like this would be sent from the server:
> {"commands":["cmd1","cmd2],"data":{"foo":"bar"}}
>
> With the above I can both get the data I need to show, and know what the
> user is allowed to do with it.
>
> Has anyone done this? Or should I skip directly to XHTML instead and use
> <a>'s to let the client know what it can do? And if so, how would the
> data be best transferred (key/value data)?
>
> Any tips would be appreciated!
>
> /Rickard
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
 


On 1/19/2010 5:47 AM, Eb wrote:
>
>
>
>
> On Tue, Jan 19, 2010 at 7:25 AM, Rickard �berg
> <rickardoberg@... <mailto:rickardoberg@...>> wrote:
>
>
>
> That's the idea. We could also replace "cmd1" with URL's instead,
> so that the client doesn't have to generate URL's, but then we
> need more info to be sent, similar to <a>'s (rel+href attributes).
>
>
>
> Introduce your own linking structure in the json representation.
> Nothing is really stopping you from returning html-like or
> atom-like attributes in your json. (At least I don't think so.).

The JSON Schema specification is worth looking at if you are want to
use JSON RESTful in a way that is visible to multiple agents. It
allows you describe the linking elements in your JSON so that agents
can navigate your data without being tightly coupled to your server.
http://tools.ietf.org/html/draft-zyp-json-schema-01#section-6

In some ways, JSON Schema is kind of the JSON equivalent of Atom; it
certainly takes a much different approach (allows for much terser data
representations), but still with the goal of providing truly hypertext
enabled data representations.

Thanks,
- -- 

Kris Zyp
SitePen
(503) 806-1841
http://sitepen.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
 
iEYEARECAAYFAktVtN8ACgkQ9VpNnHc4zAwFoQCfVg6GAOMxZwzaPeU/EaYAamlK
SDsAn1JXrTz+UU9FAplJ89YezdxSyOOU
=+2qT
-----END PGP SIGNATURE-----

On Tue, Jan 19, 2010 at 8:04 AM, Mike Kelly <mike@...> wrote:

> "Eb wrote:
>
>
>>
>>
>>
>> On Tue, Jan 19, 2010 at 7:37 AM, Mike Kelly <mike@... <mailto:
>> mike@...>> wrote:
>>
>>    Essentially just the amount of clients that understand the media type.
>>
>>    I tend to look at it in terms of concentration/dilution - i.e.
>>    custom media types are more 'concentrated', in that they have
>>    stronger meaning but to a smaller spread of clients. An equally
>>    generic media types are more dilute, in that they have weaker
>>    meaning but to a larger spread of clients.
>>
>>    Where you draw the line should depend on how wide a particular
>>    application is intended to be distributed - extending atom is an
>>    example of a good opportunity for compromise.
>>
>>    - Mike
>>
>>
>> Ok, I buy that more clients will "accept" (potentially) the media type,
>> but that doesn't really mean they understand it (from a "get stuff done"
>> perspective), if the media type has been extended to now include semantics
>> not defined into the original specification of the media type.  The client
>> will just see junk.  Maybe "reach" is the wrong word to define what we're
>> trying to describe here because I find it very misleading (personally).
>>
>>
> Your concerns point to the essence of the 'reach' concept - the idea that
> as you add custom semantics, the amount of clients able to understand
> decreases i.e. you are "reaching" less clients.
>
> Extending atom - 'basic' atom clients will see the standard atom and your
> extra junk, rather than 'just junk'. That is why you would choose to extend,
> rather than start from scratch.
>
> I don't find "reach" massively misleading - what about that terminology
> causes the problem?
>
> http://www.google.com/search?q=define:+reach
>
> " be in or establish communication with; "Our advertisements reach
> millions""
>
> " to extend as far as; "The sunlight reached the wall"; "Can he reach?"
> "The chair must not touch the wall"
>
> Cheers,
> Mike
>

:) Good point on the concept of "extend".  To gain mileage with atom, you
should be using it such that your clients can derive some value from "basic"
atom.  With that in mind, I can accept the "reach" available with using
atom.

On Jan 19, 2010, at 2:34 PM, Kris Zyp wrote:

>
> The JSON Schema specification is worth looking at if you are want to
> use JSON RESTful in a way that is visible to multiple agents.

Which reminds me of the task on my todo-list that I wanted to comment  
on the proposed way to associate schema with instance:

I think the draft proposes the wrong parameter (describedby). It would  
be better to re-use HTML's 'profile' parameter[1][2] as suggested  
here[3]

Personally, I like profiles to define identifiers for bundles of  
extensions that constitute a contract but refering to a JSON schema  
seems is conceptually not different.

I am not sure the profile parameter would be used in Content-Type  
headers, though. I think it is more usefull for conneg. Thus I'd use  
it in Accept headers or type attributes of link elements.

Jan


[1] http://tools.ietf.org/html/rfc3236#section-8
[2] http://www.w3.org/TR/html401/struct/global.html#h-7.4.4.3

[3] http://buzzword.org.uk/2009/draft-inkster-profile-parameter-00.html





> It
> allows you describe the linking elements in your JSON so that agents
> can navigate your data without being tightly coupled to your server.
> http://tools.ietf.org/html/draft-zyp-json-schema-01#section-6
>
> In some ways, JSON Schema is kind of the JSON equivalent of Atom; it
> certainly takes a much different approach (allows for much terser data
> representations), but still with the goal of providing truly hypertext
> enabled data representations.
>
> Thanks,
> - --
>
> Kris Zyp
> SitePen
> (503) 806-1841
> http://sitepen.com
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (MingW32)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
>
> iEYEARECAAYFAktVtN8ACgkQ9VpNnHc4zAwFoQCfVg6GAOMxZwzaPeU/EaYAamlK
> SDsAn1JXrTz+UU9FAplJ89YezdxSyOOU
> =+2qT
> -----END PGP SIGNATURE-----
>
>
>
> 

--------------------------------------
Jan Algermissen

Mail: algermissen@...
Blog: http://algermissen.blogspot.com/
Home: http://www.jalgermissen.com
--------------------------------------

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
 


On 1/19/2010 7:06 AM, Jan Algermissen wrote:
>
> On Jan 19, 2010, at 2:34 PM, Kris Zyp wrote:
>
>>
>> The JSON Schema specification is worth looking at if you are want to
>> use JSON RESTful in a way that is visible to multiple agents.
>
> Which reminds me of the task on my todo-list that I wanted to
> comment on the proposed way to associate schema with instance:
>
> I think the draft proposes the wrong parameter (describedby). It
> would be better to re-use HTML's 'profile' parameter[1][2] as
> suggested here[3]

Excellent, thank you for the links, that does make sense. I'll edit
that for the next draft.

>
> Personally, I like profiles to define identifiers for bundles of
> extensions that constitute a contract but refering to a JSON schema
> seems is conceptually not different.
>
> I am not sure the profile parameter would be used in Content-Type
> headers, though. I think it is more usefull for conneg. Thus I'd use
> it in Accept headers or type attributes of link elements.

Yes, I agree that it could be useful in Accept headers.
Thanks,
Kris
>
> Jan
>
>
> [1] http://tools.ietf.org/html/rfc3236#section-8
> [2] http://www.w3.org/TR/html401/struct/global.html#h-7.4.4.3
>
> [3] http://buzzword.org.uk/2009/draft-inkster-profile-parameter-00.html
>
>
>
>
>
>> It
>> allows you describe the linking elements in your JSON so that agents
>> can navigate your data without being tightly coupled to your server.
>> http://tools.ietf.org/html/draft-zyp-json-schema-01#section-6
>>
>> In some ways, JSON Schema is kind of the JSON equivalent of Atom; it
>> certainly takes a much different approach (allows for much terser data
>> representations), but still with the goal of providing truly hypertext
>> enabled data representations.
>>
>> Thanks,
>> - --
>>
>> Kris Zyp
>> SitePen
>> (503) 806-1841
>> http://sitepen.com
>> -----BEGIN PGP SIGNATURE-----
>> Version: GnuPG v1.4.9 (MingW32)
>> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
>>
>> iEYEARECAAYFAktVtN8ACgkQ9VpNnHc4zAwFoQCfVg6GAOMxZwzaPeU/EaYAamlK
>> SDsAn1JXrTz+UU9FAplJ89YezdxSyOOU
>> =+2qT
>> -----END PGP SIGNATURE-----
>>
>>
>>
>> 
>
> --------------------------------------
> Jan Algermissen
>
> Mail: algermissen@...
> Blog: http://algermissen.blogspot.com/
> Home: http://www.jalgermissen.com
> --------------------------------------
>
>
>

- -- 
Kris Zyp
SitePen
(503) 806-1841
http://sitepen.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
 
iEYEARECAAYFAktVvx8ACgkQ9VpNnHc4zAwADACfVZYP+HuwHV8Dnb3LZizjGb4E
iTwAnj0ktDbLV++IP4khQjc97jwuV6RV
=u+hQ
-----END PGP SIGNATURE-----

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
 


On 1/19/2010 4:24 PM, Robert Brewer wrote:
> Kris Zyp wrote:
>> The JSON Schema specification is worth looking at if you are want to
>> use JSON RESTful in a way that is visible to multiple agents. It
>> allows you describe the linking elements in your JSON so that agents
>> can navigate your data without being tightly coupled to your server.
>> http://tools.ietf.org/html/draft-zyp-json-schema-01#section-6
>>
>> In some ways, JSON Schema is kind of the JSON equivalent of Atom; it
>> certainly takes a much different approach (allows for much terser data
>> representations), but still with the goal of providing truly hypertext
>> enabled data representations.
>
> That's funny; I would have said JSON Schema is kind of the JSON
equivalent of XML Schema <wink>. Shoji [1] is much closer to being the
"JSON equivalent of Atom" in my head, since it actually provides
concrete, structured types rather than a schema for describing types in
general. But then you knew I was going to say that ;)

Yes, you are definitely right, Shoji is closer to Atom in structure
and approach, I should have mentioned Shoji, sorry about that. JSON
Schema's meta-definition strategy is definitely a different approach.
However, they all do provide a means for user agents to follow links
in data.

- -- 
Kris Zyp
SitePen
(503) 806-1841
http://sitepen.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
 
iEYEARECAAYFAktWQMAACgkQ9VpNnHc4zAya8gCfVamp5N62ypfZ8PHvZH3IkY3r
9BEAnRdfL/QBCaqgZT/1lwX7eBpVyuRT
=I3YC
-----END PGP SIGNATURE-----

Kris Zyp wrote:
> The JSON Schema specification is worth looking at if you are want to
> use JSON RESTful in a way that is visible to multiple agents. It
> allows you describe the linking elements in your JSON so that agents
> can navigate your data without being tightly coupled to your server.
> http://tools.ietf.org/html/draft-zyp-json-schema-01#section-6
> 
> In some ways, JSON Schema is kind of the JSON equivalent of Atom; it
> certainly takes a much different approach (allows for much terser data
> representations), but still with the goal of providing truly hypertext
> enabled data representations.

That's funny; I would have said JSON Schema is kind of the JSON equivalent of XML Schema <wink>. Shoji [1] is much closer to being the "JSON equivalent of Atom" in my head, since it actually provides concrete, structured types rather than a schema for describing types in general. But then you knew I was going to say that ;)


Robert Brewer
fumanchu@...

[1] http://www.aminus.org/rbre/shoji/shoji-draft-01.txt

This may be a naive question, as I've only just joined the
"rest-discuss" list in the past few days.

I'm contemplating how to apply a REST approach to use cases where the
primary client is likely not the browser, but other enterprise software
that might otherwise be using SOAP services.

Looking around the 'net, I've answered a lot of questions, but here's
one I'm stumped about.

Are there recommended approaches for supporting single-sign-on (SSO)
with REST over HTTP for the scenario I've described?

-Eric

On Wed, Jan 20, 2010 at 3:29 PM, Eric Johnson <eric@...> wrote:

>
>
> This may be a naive question, as I've only just joined the
> "rest-discuss" list in the past few days.
>
> I'm contemplating how to apply a REST approach to use cases where the
> primary client is likely not the browser, but other enterprise software
> that might otherwise be using SOAP services.
>
> Looking around the 'net, I've answered a lot of questions, but here's
> one I'm stumped about.
>
> Are there recommended approaches for supporting single-sign-on (SSO)
> with REST over HTTP for the scenario I've described?
>
> Authentication is always a question that comes up early-on when looking at
RESTful architectures.  You'll want to investigate what HTTP itself offers
in that realm (specifically Basic and Digest authentication).  It doesn't
address SSO per-se, but gets at what needs to happen as part of the
request-response cycle.

Beyond that, I would take a good look at OpenID and OAuth.  These are the
two technologies developed as "open" standards that point to the right way
of doing Auth/Authz on the web.

That's a kind of vague answer, but will (I hope) point you in a good
direction for further research.

--peter




> -Eric
>  
>

Hello

I am struggling with how to protect resources that are exposed through a service.

Assuming the authentication part is 'done' it still seems necessary to have a fairly detailed control on who can read/write attributes and/or add/remove resources to collections.

To a certain extent this same question is raised in http://stackoverflow.com/questions/1408571/restful-authorization 

(please ignore, in that post, the remarks on crud,active record and the likes...that is not what the question is about).

My questions is really on what best practices are around to have relatively find grained control on 'who' can do 'what' with a given resource. Control that goes beyond authorizing the REST verbs being used on a resource.

A few simple examples

- The price of a given order item should be 'readable' by the 'creator' of the order item while an 'administrator' should be able to update the price
- An collection of order states (not a separate resource but part of the order) should be readable by the 'creator'. An 'administrator' should be able to add states
- ...

I hope I made myself clear.


Any pointers to material covering these types of issues is warmly welcomed

Thanks

Peter

Hi all, 

I was wondering if there was interest for creating a blog which would list relevant REST activities on a weekly basis? Following all REST-related development on the WWW is somewhat a hassle since there's a lot to follow: this discussion group, a lot of blogs covering both REST and non-REST stuff and a lot of other pages (projects, frameworks, news articles, scientific papers...) which are hard to search for since "REST" is not a very good query. 

What I'd like is a brief overview of only and all things REST that happened in the last week and to be able to receive that overview through my feed reader. A blog feels right for delivery, but raises the question of who would maintain it and how. A collaborative approach where everyone would send links to a single person which would compile the blog post would work. An alternative would be creating a wiki page for collaborative link gathering, but leaves the question of how the overview would be delivered on a weekly basis. Another alternative would be to use this group for both gathering links (as replies to a single request-for-links weekly post) and publishing the weekly overview (as a new weekly post).

Anyway, what do you think? 

Cheers,
Ivan

On Thu, Jan 21, 2010 at 12:40 AM, pgp.coppens
<pc.subscriptions@...> wrote:
> Hello
>
> I am struggling with how to protect resources that are exposed through a service.
>
> Assuming the authentication part is 'done' it still seems necessary to
> have a fairly detailed control on who can read/write attributes and/or
> add/remove resources to collections.

To be honest, this doesn't have anything, per se, to do with REST.
That is, REST doesn't bring anything to the table to address, nor does
it limit what can or should be done.

The only "obligation", perhaps, of REST is discussion about a
mechanism(s) for providing Authentication and Identification
information. Authorization is a domain problem, not necessarily an
architectural (at the level that REST is sitting at least) issue.

The only real area where there is any potential crossover is simply
that two clients may well get two different representations for the
same resource. For example, the Purchaser of a product might be able
to see item, quantity and price on a Order, but a Shipper, may well
simply be able to see item and quantity.

But as long as the roles are consistent, this isn't a problem. There's
nothing wrong with a Shipper having "read only", and a "limited" view
of a resource compared to another role.

You can see, though, that a REST system is pretty much ambivalent to
the roles and their effects, and beyond being able to identify users,
actual processing and limitations of roles are done at the domain
level.

Regards,

Will Hartung
(willh@...)

Hi Peter,

Will's right when he says "REST" has nothing to with this. But there are regular ways of dealing with this using HTTP.

> - The price of a given order item should be 'readable' by the 'creator' of the order item while an 'administrator' should be able to update the price

Using one of the HTTP authentication mechanisms (or OpenID, OAuth even) the creator will happily receive 401 when applying some verbs (e.g. PUT, DELETE) to a resource (e.g. pricing) but find they're get 200 OK responses to other verbs (e.g. GET). The administrator might find they receive 200 OK responses to all of those operations.

> - An collection of order states (not a separate resource but part of the order) should be readable by the 'creator'. An 'administrator' should be able to add states

How the order is projected onto the Web in terms of resources is an implementation decision. You might choose to have the collection of order states physically written down on the same piece of paper in your back end, but you could still happily project them as different logical resources onto the Web. Hypermedia is your friend should you want to link them together. Eg:

Administrator: GET/order/1234
200 OK....
<order>
<atom:link href="http://myservice/order/1234/state" rel="order-state" type="application/x.ordering+xml"/>
<line-item> ... </lineItem>
</order>

Creator: GET/order/1234
200 OK...
<order>
<line-item> ... </lineItem>
</order>

Creator, after some creative thought tries: GET http://myservice/order/1234/state
401 Unauthorized...

Nonetheless, administrators will have more chance of a 200 OK response than creators just as above.

Does that help at all?

Jim

The most effective way to handle authorization (not authentication) of
resources over HTTP is to map access control to the resource URI + the
HTTP Method for a user (or group).

I often use the following "model" (here in XML) to express
authorization rights in HTTP apps:
<user id="user">
  <access href="/orders/" action="GET,HEAD,OPTIONS" />
</user>
<user id="manager">
  <access href="/orders/" action="GET,HEAD,OPTIONS,POST,PUT" />
</user>
<user id="administrator">
  <access href="/orders/" action="GET,HEAD,OPTIONS,POST,PUT,DELETE" />
</user>

Typical optimizations I employ are:
<access href="/orders/" action="*" /> <!-- all methods allowed -->
<access href="/orders/" action="!" /> <!-- no methods allowed -->
<access href="/*" action="*" /> <!-- all URIs, all methods (handy for
sys-admin role -->
Regular expressions come in handy here, too.

I also optimize the "user id" to include either a username (possibly
expressed as an email address, FOAF URI, etc.) or groupname (users
mapped to groups) and the use of an "owner" moniker to allow owners
(creators) unique access to a particular resource where that makes
sense.

mca
http://amundsen.com/blog/




On Thu, Jan 21, 2010 at 16:46, Jim Webber <jim@...> wrote:
> Hi Peter,
>
> Will's right when he says "REST" has nothing to with this. But there are regular ways of dealing with this using HTTP.
>
>> - The price of a given order item should be 'readable' by the 'creator' of the order item while an 'administrator' should be able to update the price
>
> Using one of the HTTP authentication mechanisms (or OpenID, OAuth even) the creator will happily receive 401 when applying some verbs (e.g. PUT, DELETE) to a resource (e.g. pricing) but find they're get 200 OK responses to other verbs (e.g. GET). The administrator might find they receive 200 OK responses to all of those operations.
>
>> - An collection of order states (not a separate resource but part of the order) should be readable by the 'creator'. An 'administrator' should be able to add states
>
> How the order is projected onto the Web in terms of resources is an implementation decision. You might choose to have the collection of order states physically written down on the same piece of paper in your back end, but you could still happily project them as different logical resources onto the Web. Hypermedia is your friend should you want to link them together. Eg:
>
> Administrator: GET/order/1234
> 200 OK....
> <order>
> <atom:link href="http://myservice/order/1234/state" rel="order-state" type="application/x.ordering+xml"/>
> <line-item> ... </lineItem>
> </order>
>
> Creator: GET/order/1234
> 200 OK...
> <order>
> <line-item> ... </lineItem>
> </order>
>
> Creator, after some creative thought tries: GET http://myservice/order/1234/state
> 401 Unauthorized...
>
> Nonetheless, administrators will have more chance of a 200 OK response than creators just as above.
>
> Does that help at all?
>
> Jim
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

What about allowing folks to submit links to a feed aggregator? One
could submit a single link of an interesting post/article or could
submit a feed link to a blog/site that can be fetched regularly. It
might also be interesting to establish and publish tags (#rest, etc.)
authors can use to mark their content for bots that can use these tags
to find relevant material and add the links to the aggregator.

mca
http://amundsen.com/blog/




On Thu, Jan 21, 2010 at 15:54, izuzak <izuzak@...> wrote:
> Hi all,
>
> I was wondering if there was interest for creating a blog which would list relevant REST activities on a weekly basis? Following all REST-related development on the WWW is somewhat a hassle since there's a lot to follow: this discussion group, a lot of blogs covering both REST and non-REST stuff and a lot of other pages (projects, frameworks, news articles, scientific papers...) which are hard to search for since "REST" is not a very good query.
>
> What I'd like is a brief overview of only and all things REST that happened in the last week and to be able to receive that overview through my feed reader. A blog feels right for delivery, but raises the question of who would maintain it and how. A collaborative approach where everyone would send links to a single person which would compile the blog post would work. An alternative would be creating a wiki page for collaborative link gathering, but leaves the question of how the overview would be delivered on a weekly basis. Another alternative would be to use this group for both gathering links (as replies to a single request-for-links weekly post) and publishing the weekly overview (as a new weekly post).
>
> Anyway, what do you think?
>
> Cheers,
> Ivan
>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

Hi Peter,

Thanks for the response.

On 01/20/2010 02:35 PM, Peter Keane wrote:
> On Wed, Jan 20, 2010 at 3:29 PM, Eric Johnson <eric@...
> <mailto:eric@...>> wrote:
>
>     I'm contemplating how to apply a REST approach to use cases where the
>     primary client is likely not the browser, but other enterprise
>     software
>     that might otherwise be using SOAP services.
>
>     Are there recommended approaches for supporting single-sign-on (SSO)
>     with REST over HTTP for the scenario I've described?
>
> Authentication is always a question that comes up early-on when
> looking at RESTful architectures.  You'll want to investigate what
> HTTP itself offers in that realm (specifically Basic and Digest
> authentication).  It doesn't address SSO per-se, but gets at what
> needs to happen as part of the request-response cycle. 

I've done enough with the standard HTTP authentication to recognize that
what you're saying is theoretically possible, but if all I've got to go
with that's a cross-platform standard is "Basic" and "Digest", that
really doesn't get me single-sign-on - there's no guarantee that the
current client has the credentials on hand.  Were I implementing SOAP
services, I'd probably be supporting/using SAML, for example.

>
> Beyond that, I would take a good look at OpenID and OAuth.  These are
> the two technologies developed as "open" standards that point to the
> right way of doing Auth/Authz on the web.

OpenID and oauth look promising.  I was aware of OpenID.  It looks like
OpenID is more suited for a browser interface, where clients expect HTML
responses that contain prompts for the user.  For my enterprise usage,
where the REST clients aren't the browser, that means a lot of extra
"scraping" work for clients, at best.  Am I mis-reading that spec?

OAuth looks like it is intended for the program-as-client side of the
problem-space.  That sounds like just what I need, in that I can then
write programs that consume custom media types in the service of our
enterprise software.  Yet I note that, as yet, oauth is not an IETF
published draft.  Poking around the internet, I didn't see any
immediately obvious reports about its expected future (imminent success?
substantial changes expected? slow death... unlikely!).

Before I rush to suggest that my company do a lot of work around oauth,
what are the caveats for using it?

>
> That's a kind of vague answer, but will (I hope) point you in a good
> direction for further research.

Definitely helpful.  I've been doing research. Still more to do.  Thanks!

-Eric.

Hello Eric,

> OpenID and oauth look promising.  I was aware of OpenID.  It looks like
> OpenID is more suited for a browser interface, where clients expect HTML
> responses that contain prompts for the user.  For my enterprise usage,
> where the REST clients aren't the browser, that means a lot of extra
> "scraping" work for clients, at best.  Am I mis-reading that spec?

Ah, well OpenID was originally developed for user-centric use-cases, but there's no reason that you can't use it for computer-to-computer scenarios either. It's just exchanging a bunch of hypermedia documents (XHTML forms) between three parties really. In fact Ian, Savas, and I have developed an example doing just this for our book (apologies to the list for harping on about an incomplete book, again).

> Before I rush to suggest that my company do a lot of work around oauth,
> what are the caveats for using it?

Nothing, apart from it's still a bit of a moving target AFAIK. (and at the risk of incurring the wrath-of-rest, it's in our book).

Jim

Mike - that's not a bad idea also. Getting all relevant REST-related
content on a regular basis is the goal and without people contributing
in some way - I don't see it happening.

Not to be nit-picky, but I myself would like a single post/page
listing all the relevant articles with a short one line overview
(versus a stream of links with possible duplicates and no structure).
Something like the XMPP Roundup -
http://blog.xmpp.org/index.php/2009/09/xmpp-roundup-12/. Jim Webber
also pointed me to Scott Banwart's "Distributed Weekly" blog which
basically covers what I had in mind -
http://rogue-technology.com/blog/. Ideally, the blog would be only
REST oriented and cover more stuff, e.g. posts on the REST discussion
group.

I don't mind creating and maintaining a new
wiki/blog/whetever-we-like-the-most for this purpose if people here
feel it's something that adds value and would contribute.

Anyone else like any of these ideas? :)

Thanks,
Ivan


On Thu, Jan 21, 2010 at 23:51, mike amundsen <mamund@...> wrote:
> What about allowing folks to submit links to a feed aggregator? One
> could submit a single link of an interesting post/article or could
> submit a feed link to a blog/site that can be fetched regularly. It
> might also be interesting to establish and publish tags (#rest, etc.)
> authors can use to mark their content for bots that can use these tags
> to find relevant material and add the links to the aggregator.
>
> mca
> http://amundsen.com/blog/
>
>
>
>
> On Thu, Jan 21, 2010 at 15:54, izuzak <izuzak@...> wrote:
>> Hi all,
>>
>> I was wondering if there was interest for creating a blog which would list relevant REST activities on a weekly basis? Following all REST-related development on the WWW is somewhat a hassle since there's a lot to follow: this discussion group, a lot of blogs covering both REST and non-REST stuff and a lot of other pages (projects, frameworks, news articles, scientific papers...) which are hard to search for since "REST" is not a very good query.
>>
>> What I'd like is a brief overview of only and all things REST that happened in the last week and to be able to receive that overview through my feed reader. A blog feels right for delivery, but raises the question of who would maintain it and how. A collaborative approach where everyone would send links to a single person which would compile the blog post would work. An alternative would be creating a wiki page for collaborative link gathering, but leaves the question of how the overview would be delivered on a weekly basis. Another alternative would be to use this group for both gathering links (as replies to a single request-for-links weekly post) and publishing the weekly overview (as a new weekly post).
>>
>> Anyway, what do you think?
>>
>> Cheers,
>> Ivan
>>
>>
>>
>> ------------------------------------
>>
>> Yahoo! Groups Links
>>
>>
>>
>>
>

On Jan 21, 2010, at 9:54 PM, izuzak wrote:

> Hi all,
>
> I was wondering if there was interest for creating a blog which  
> would list relevant REST activities on a weekly basis?

Why not use the REST wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?WebWeekly 
  and see where that goes?

Jan


> Following all REST-related development on the WWW is somewhat a  
> hassle since there's a lot to follow: this discussion group, a lot  
> of blogs covering both REST and non-REST stuff and a lot of other  
> pages (projects, frameworks, news articles, scientific papers...)  
> which are hard to search for since "REST" is not a very good query.
>
> What I'd like is a brief overview of only and all things REST that  
> happened in the last week and to be able to receive that overview  
> through my feed reader. A blog feels right for delivery, but raises  
> the question of who would maintain it and how. A collaborative  
> approach where everyone would send links to a single person which  
> would compile the blog post would work. An alternative would be  
> creating a wiki page for collaborative link gathering, but leaves  
> the question of how the overview would be delivered on a weekly  
> basis. Another alternative would be to use this group for both  
> gathering links (as replies to a single request-for-links weekly  
> post) and publishing the weekly overview (as a new weekly post).
>
> Anyway, what do you think?
>
> Cheers,
> Ivan
>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

-----------------------------------
  Jan Algermissen, Consultant

  Mail: algermissen@...
  Blog: http://www.nordsc.com/blog/
  Work: http://www.nordsc.com/
-----------------------------------

On Fri, Jan 22, 2010 at 11:30, Jan Algermissen <algermissen1971@...> wrote:
>
> On Jan 21, 2010, at 9:54 PM, izuzak wrote:
>
>> Hi all,
>>
>> I was wondering if there was interest for creating a blog which would list
>> relevant REST activities on a weekly basis?
>
> Why not use the REST wiki:
> http://rest.blueoxen.net/cgi-bin/wiki.pl?WebWeekly and see where that goes?
>
> Jan

Sounds like a good idea to me. Let's give it a try next week.

Ivan

On Fri, Jan 22, 2010 at 3:30 AM, Jan Algermissen
<algermissen1971@...> wrote:
>
> Why not use the REST wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?WebWeekly
> �and see where that goes?

One issue: It is not obvious how one would subscribe to just WebWeekly
pages.  Personally, would want these weekly updates to show up in my
feed read but not the other pages from the wiki.

(Actually, the rss feed for the wiki is completely broken for me at
the moment.  Error message says `Can't call method "loadUser" on an
undefined value at /data/www/perl2/PurpleWiki/Syndication/Rss.pm line
80.`)

I like the idea of a weekly roundup (assuming subscribing to it is
easy) but i think a REST planet (like Mike suggested) would be nice
too.

Peter

I'm hearing that before issuing a HTTP PUT request from JavaScript, more 
recent browsers are sending out HTTP OPTIONS on the request resource to 
verify that the PUT method is supported. If the OPTIONS request returns 
with a 200 OK and specifies that PUT is allowed everything is alright. 
If not the browser will not execute the PUT (whether or not the resource 
supports it). Is this sane behavior from a UA, to check for just one method?

Bill

<snip>
I'm hearing that before issuing a HTTP PUT request from JavaScript,
more recent browsers are sending out HTTP OPTIONS on the request
resource to verify that the PUT method is supported.
</snip>

I've not heard this before. I just did a quick scan of some server
logs and find no evidence that this is happening right now in a couple
apps that use PUT via XMLHttpRequest.

mca
http://amundsen.com/blog/




On Fri, Jan 22, 2010 at 11:48, Bill de hOra <bill@...> wrote:
>
> I'm hearing that before issuing a HTTP PUT request from JavaScript, more
> recent browsers are sending out HTTP OPTIONS on the request resource to
> verify that the PUT method is supported. If the OPTIONS request returns
> with a 200 OK and specifies that PUT is allowed everything is alright.
> If not the browser will not execute the PUT (whether or not the resource
> supports it). Is this sane behavior from a UA, to check for just one method?
>
> Bill
>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
 


On 1/22/2010 9:48 AM, Bill de hOra wrote:
>
>
>
> I'm hearing that before issuing a HTTP PUT request from
> JavaScript, more recent browsers are sending out HTTP OPTIONS on
> the request resource to verify that the PUT method is supported. If
> the OPTIONS request returns with a 200 OK and specifies that PUT is
> allowed everything is alright. If not the browser will not execute
> the PUT (whether or not the resource supports it). Is this sane
> behavior from a UA, to check for just one method?
>

Just to make sure this is clear, this is for cross-origin XHR
requests, per http://www.w3.org/TR/access-control/. These requests
were not possible before, and the OPTIONS request is to ensure that
the server is prepared to handle requests from the browser that used
to be blocked, to prevent new security breaches.
Kris
>
>
> Bill
>
> 

- -- 
Kris Zyp
SitePen
(503) 806-1841
http://sitepen.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
 
iEYEARECAAYFAktZ2d8ACgkQ9VpNnHc4zAx4oQCeIbnNwM/bCX5jMDAz7J9zgttg
i1EAn3eC0LhLHVL4v77cAbExP319HQMh
=bj7m
-----END PGP SIGNATURE-----

Bill de hOra wrote:
> 
> I'm hearing that before issuing a HTTP PUT request from JavaScript,
> more recent browsers are sending out HTTP OPTIONS on the request
> resource to verify that the PUT method is supported. If the OPTIONS
> request returns with a 200 OK and specifies that PUT is allowed
> everything is alright. If not the browser will not execute the PUT
> (whether or not the resource supports it). Is this sane behavior from
> a UA, to check for just one method?
> 

I think it's incorrect behavior.  Many httpds are hard-coded to respond
to OPTIONS requests by sending the Allow header.  But, there's no reason
not to make Allow available in response to HEAD requests.  Otherwise
you get into the issue of what sort of entity to return with OPTIONS,
and that's undefined territory.

Whereas, if the request simply intends to check a resource header, no
entity is needed.  So I send Allow in response to both GET and HEAD,
and keep OPTIONS unimplemented until I've figured out what to do with
it (a backend management interface, perhaps).

IMO, what a UA SHOULD do, is to see if a HEAD request generates an
Allow response header before falling back to the less-desirable OPTIONS.
Do it right, instead of hard-coding an archaic and inefficient solution
to retrieving Allow headers.

-Eric

Eric Johnson wrote:

> Before I rush to suggest that my company do a lot of work around oauth, 
> what are the caveats for using it?


It's tricky for mobile and machine driven systems - the point of Oauth 
is to put a human in the loop to avoid the password anti-pattern and it 
more or less has a baked in assumption the human is using a browser. 
Myself and a colleague wrote an RFC for a 2-legged model to deal with 
those issues last year [1], I heard that Twitter are adopting it. 
OAuth2.0/Wrap are interesting things to watch [2].

Bill

[1] 
http://tools.ietf.org/html/draft-dehora-farrell-oauth-accesstoken-creds-01
[2] http://radar.oreilly.com/2010/01/whats-going-on-with-oauth.html

As a server implementer, why should I have to implement OPTIONS just to
support PUT for clients which incorrectly treat the Allow header as
authoritative?  I have enough on my plate...

-Eric

"Eric J. Bowman" wrote:
>
> Bill de hOra wrote:
> > 
> > I'm hearing that before issuing a HTTP PUT request from JavaScript,
> > more recent browsers are sending out HTTP OPTIONS on the request
> > resource to verify that the PUT method is supported. If the OPTIONS
> > request returns with a 200 OK and specifies that PUT is allowed
> > everything is alright. If not the browser will not execute the PUT
> > (whether or not the resource supports it). Is this sane behavior
> > from a UA, to check for just one method?
> > 
> 
> I think it's incorrect behavior.  Many httpds are hard-coded to
> respond to OPTIONS requests by sending the Allow header.  But,
> there's no reason not to make Allow available in response to HEAD
> requests.  Otherwise you get into the issue of what sort of entity to
> return with OPTIONS, and that's undefined territory.
> 
> Whereas, if the request simply intends to check a resource header, no
> entity is needed.  So I send Allow in response to both GET and HEAD,
> and keep OPTIONS unimplemented until I've figured out what to do with
> it (a backend management interface, perhaps).
> 
> IMO, what a UA SHOULD do, is to see if a HEAD request generates an
> Allow response header before falling back to the less-desirable
> OPTIONS. Do it right, instead of hard-coding an archaic and
> inefficient solution to retrieving Allow headers.
> 
> -Eric
> 

On Fri, Jan 22, 2010 at 9:22 AM, Bill de hOra <bill@...> wrote:

> It's tricky for mobile and machine driven systems - the point of Oauth
> is to put a human in the loop to avoid the password anti-pattern and it
> more or less has a baked in assumption the human is using a browser.
> Myself and a colleague wrote an RFC for a 2-legged model to deal with
> those issues last year [1], I heard that Twitter are adopting it.
> OAuth2.0/Wrap are interesting things to watch [2].

I have no experience with it, but from what I saw with OAuth, it
didn't seem abusive to machine systems, rather it required the machine
systems to understand the credential exchange requirements of a
specific provider.

For an an in house system, this didn't seem like much of a burden. For
a "generic" client, then, certainly. A generic client would need to
"know" about the nuances of specific providers.

Once that hurdle was passed, it looked pretty good overall to me.

Regards,

Will Hartung
(willh@...)

On Fri, Jan 22, 2010 at 9:24 AM, Eric J. Bowman <eric@...> wrote:

> As a server implementer, why should I have to implement OPTIONS just to
> support PUT for clients which incorrectly treat the Allow header as
> authoritative? I have enough on my plate...

Particularly if the UA just got a payload with links that specify PUT,
the UA then "already knows" what it can do, so why should it be asking
again.

Also, why make the extra request? The UA can't know when or when not
the server is going to allow or disallow such a request. If the server
doesn't support PUT, then it will (should) inform the client properly
when it's tried.

It's not like the UA can cache the OPTIONS response. So, why invoke
new overhead? And why not do the same for GET, POST and DELETE?

Makes no sense to me. Bad assumption, and weak to non-existent protection.

Regards,

Will Hartung
(willh@...)

<snip>
Just to make sure this is clear, this is for cross-origin XHR requests, per
http://www.w3.org/TR/access-control/.
</snip>

Oh, yeah; forgot about this draft - thanks for the reminder, Kris.

Using an additional preflight [1] request via OPTIONS on all cross-site
origin requests other than GET, HEAD, and POST.

[1] http://www.w3.org/TR/2009/WD-cors-20090317/#preflight-request0
<http://www.w3.org/TR/2009/WD-cors-20090317/#preflight-request0>
mca
http://amundsen.com/blog/



On Fri, Jan 22, 2010 at 12:01, Kris Zyp <kris@...> wrote:

>
>
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
>
>
> On 1/22/2010 9:48 AM, Bill de hOra wrote:
> >
> >
> >
> > I'm hearing that before issuing a HTTP PUT request from
> > JavaScript, more recent browsers are sending out HTTP OPTIONS on
> > the request resource to verify that the PUT method is supported. If
> > the OPTIONS request returns with a 200 OK and specifies that PUT is
> > allowed everything is alright. If not the browser will not execute
> > the PUT (whether or not the resource supports it). Is this sane
> > behavior from a UA, to check for just one method?
> >
>
> Just to make sure this is clear, this is for cross-origin XHR
> requests, per http://www.w3.org/TR/access-control/. These requests
> were not possible before, and the OPTIONS request is to ensure that
> the server is prepared to handle requests from the browser that used
> to be blocked, to prevent new security breaches.
> Kris
> >
> >
> > Bill
> >
> >
>
> - --
> Kris Zyp
> SitePen
> (503) 806-1841
> http://sitepen.com
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (MingW32)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
>
> iEYEARECAAYFAktZ2d8ACgkQ9VpNnHc4zAx4oQCeIbnNwM/bCX5jMDAz7J9zgttg
> i1EAn3eC0LhLHVL4v77cAbExP319HQMh
> =bj7m
> -----END PGP SIGNATURE-----
>
>
>
> 

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
 

On 1/22/2010 10:39 AM, Will Hartung wrote:
>
>
> [snip] It's not like the UA can cache the OPTIONS response. So, why
> invoke new overhead? And why not do the same for GET, POST and
> DELETE?
>
> Makes no sense to me. Bad assumption, and weak to non-existent
> protection.
>

If you'd like to read a more detailed rationale for (as well against)
CORS (cross-origin request sharing), you can peruse the webapps mail
archives:
http://lists.w3.org/Archives/Public/public-webapps/ (searching for
cors helps narrow down). The spec itself does include a little bit of
rationale, but it is very brief:
http://www.w3.org/TR/access-control/#design-decision-faq

- -- 
Kris Zyp
SitePen
(503) 806-1841
http://sitepen.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
 
iEYEARECAAYFAktZ5esACgkQ9VpNnHc4zAydHQCglShUoHsSsWscqfyZDJLdvl1D
idwAn3cgA32gOq0TWJcxWz0lpsWhN3Jn
=hNCB
-----END PGP SIGNATURE-----

Thanks Kris.

But I'm pretty confused. Should browsers be doing this unilaterally or 
should the server flag it understands this constraining of http?

Bill

Kris Zyp wrote:
>  
> 
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>  
> 
> On 1/22/2010 10:39 AM, Will Hartung wrote:
>>
>>
>>  [snip] It's not like the UA can cache the OPTIONS response. So, why
>>  invoke new overhead? And why not do the same for GET, POST and
>>  DELETE?
>>
>>  Makes no sense to me. Bad assumption, and weak to non-existent
>>  protection.
>>
> 
> If you'd like to read a more detailed rationale for (as well against)
> CORS (cross-origin request sharing), you can peruse the webapps mail
> archives:
> http://lists.w3.org/Archives/Public/public-webapps/ (searching for
> cors helps narrow down). The spec itself does include a little bit of
> rationale, but it is very brief:
> http://www.w3.org/TR/access-control/#design-decision-faq
> 
> - --
> Kris Zyp
> SitePen
> (503) 806-1841
> http://sitepen.com
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (MingW32)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
>  
> iEYEARECAAYFAktZ5esACgkQ9VpNnHc4zAydHQCglShUoHsSsWscqfyZDJLdvl1D
> idwAn3cgA32gOq0TWJcxWz0lpsWhN3Jn
> =hNCB
> -----END PGP SIGNATURE-----
> 
> 

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
 


On 1/22/2010 1:36 PM, Bill de hOra wrote:
> Thanks Kris.
>
> But I'm pretty confused. Should browsers be doing this
> unilaterally or should the server flag it understands this
> constraining of http?

The intent is that the OPTIONS request allows the server to indicate
that it can safely handle HTTP requests from the web page without
incorrect assumptions about authority implied by the included cookies
or authorization headers. All of the constraints specified by the CORS
spec are for the purpose of preventing CSRF attacks. CSRF is already a
big problem on the web, and if unconstrained cross-origin requests
could be made by malicious web sites (which include target host
cookies, and thus many application servers would consider it be an
authorized request) then CSRF problems would certainly increase.
Therefore the specification's goal is to open up the ability to make
cross-origin XHR requests in such a way that servers can opt-in and
avoid introducing new CSRF problems. Does that make sense?
- -- 
Kris Zyp
SitePen
(503) 806-1841
http://sitepen.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
 
iEYEARECAAYFAktaJaIACgkQ9VpNnHc4zAyeGwCfer8hJLWHCZpr5pah0M3NddxF
KfkAn2kJlyTsQx8iu8JzQZ9B0h21Oqt7
=BTH8
-----END PGP SIGNATURE-----

Right... the wiki solves only one part of the "problem" (collecting relevant links), but does not solve the periodic distribution. As I said, I don't mind setting up a blog to which I'd publish the weekly links if the wiki part seems to work for collecting information.

So, let's give the wiki a try first and see how it goes.

Ivan

--- In rest-discuss@yahoogroups.com, Peter Williams <pezra@...> wrote:
>
> On Fri, Jan 22, 2010 at 3:30 AM, Jan Algermissen
> <algermissen1971@...> wrote:
> >
> > Why not use the REST wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?WebWeekly
> > �and see where that goes?
> 
> One issue: It is not obvious how one would subscribe to just WebWeekly
> pages.  Personally, would want these weekly updates to show up in my
> feed read but not the other pages from the wiki.
> 
> (Actually, the rss feed for the wiki is completely broken for me at
> the moment.  Error message says `Can't call method "loadUser" on an
> undefined value at /data/www/perl2/PurpleWiki/Syndication/Rss.pm line
> 80.`)
> 
> I like the idea of a weekly roundup (assuming subscribing to it is
> easy) but i think a REST planet (like Mike suggested) would be nice
> too.
> 
> Peter
>

When a client is in a steady state, what makes up the meaning of the state (what information does the client use to determine the meaning)?

a) The current representation (plus the understanding of the media types)
b) The current representation (plus the understanding of the media types) and the request the client made (the knowledge of the semantics of the resource that the representation has been obtained from)
c) b) and knowledge about all the requests it made before (this is wrong from a REST POV, but I include it for completeness)

Note that b) includes knowledge about any conneg that might have happened. E.g. the client might have asked for

 GET /products/6676
 Accept: application/xhtml+xml;profile="http://foo.org/my-html-product-representation-uformats-profile

and the server might have just answered with

 200 Ok
 Content-Type: application/xhtml+xml

knowing that it serves the requested profile. (it did not say: your request for HTML with tht profile is 406 Not Acceptable). From the pure representation it is not detectable that the server sent this as a response to a request for 'a product representation'


My understanding is b) but I am not entirely sure.


Jan

I've never seen a ;profile attribute for a media type before, where
does this come from?  My apologies if I've overlooked it...

As to the issue of steady-states, consider the browser.  The user
follows one link, but the next steady-state may only be achieved by
dereferencing pertinent URIs within the initial representation.  Your
post implies that there's a 1:1 relationship between that initial
representation's retrieval and the next steady-state.

-Eric

"algermissen1971" wrote:
>
> When a client is in a steady state, what makes up the meaning of the
> state (what information does the client use to determine the meaning)?
> 
> a) The current representation (plus the understanding of the media
> types) b) The current representation (plus the understanding of the
> media types) and the request the client made (the knowledge of the
> semantics of the resource that the representation has been obtained
> from) c) b) and knowledge about all the requests it made before (this
> is wrong from a REST POV, but I include it for completeness)
> 
> Note that b) includes knowledge about any conneg that might have
> happened. E.g. the client might have asked for
> 
>  GET /products/6676
>  Accept: application/xhtml
> +xml;profile="http://foo.org/my-html-product-representation-uformats-profile
> 
> and the server might have just answered with
> 
>  200 Ok
>  Content-Type: application/xhtml+xml
> 
> knowing that it serves the requested profile. (it did not say: your
> request for HTML with tht profile is 406 Not Acceptable). From the
> pure representation it is not detectable that the server sent this as
> a response to a request for 'a product representation'
> 
> 
> My understanding is b) but I am not entirely sure.
> 
> 
> Jan
> 
> 
> 

--- In rest-discuss@yahoogroups.com, "Eric J. Bowman" <eric@...> wrote:
>
> I've never seen a ;profile attribute for a media type before, where
> does this come from?  My apologies if I've overlooked it...

See references in <http://tech.groups.yahoo.com/group/rest-discuss/message/14612>

It was just one aspect of my question, though.

Consider this: is the media type of a representation telling you enough to understand the current state or do you need the context of the request also? When you follow some <link rel="/featured-product" href="/products/3776"/> link and the servers sends an HTML page back do you understand the meaning of the steady state from looking at the Content-Type header or do you add-in the information that the server told you the resource you just requested is 'the featured product'?



> As to the issue of steady-states, consider the browser.  The user
> follows one link, but the next steady-state may only be achieved by
> dereferencing pertinent URIs within the initial representation.  Your
> post implies that there's a 1:1 relationship between that initial
> representation's retrieval and the next steady-state.

No. At least I did not want to imply that. The steady state is reached when all the outstanding sub-requests have been made and then, when the client has no pending requests - on what basis does it determine the meaning of the state?

In a machine client this would mean: "what information is taken into account to determine the next transition to follow? Just the media types of the steady state or also the context of the request?

Jan

> 
> -Eric
> 
> "algermissen1971" wrote:
> >
> > When a client is in a steady state, what makes up the meaning of the
> > state (what information does the client use to determine the meaning)?
> > 
> > a) The current representation (plus the understanding of the media
> > types) b) The current representation (plus the understanding of the
> > media types) and the request the client made (the knowledge of the
> > semantics of the resource that the representation has been obtained
> > from) c) b) and knowledge about all the requests it made before (this
> > is wrong from a REST POV, but I include it for completeness)
> > 
> > Note that b) includes knowledge about any conneg that might have
> > happened. E.g. the client might have asked for
> > 
> >  GET /products/6676
> >  Accept: application/xhtml
> > +xml;profile="http://foo.org/my-html-product-representation-uformats-profile
> > 
> > and the server might have just answered with
> > 
> >  200 Ok
> >  Content-Type: application/xhtml+xml
> > 
> > knowing that it serves the requested profile. (it did not say: your
> > request for HTML with tht profile is 406 Not Acceptable). From the
> > pure representation it is not detectable that the server sent this as
> > a response to a request for 'a product representation'
> > 
> > 
> > My understanding is b) but I am not entirely sure.
> > 
> > 
> > Jan
> > 
> > 
> >
>

--- In rest-discuss@yahoogroups.com, "algermissen1971" <algermissen1971@...> wrote:
>
> 
> 
> --- In rest-discuss@yahoogroups.com, "Eric J. Bowman" <eric@> wrote:
> >
> > I've never seen a ;profile attribute for a media type before, where
> > does this come from?  My apologies if I've overlooked it...
> 
> See references in <http://tech.groups.yahoo.com/group/rest-discuss/message/14612>
> 
> It was just one aspect of my question, though.
> 
> Consider this: is the media type of a representation telling you enough to understand the current state or do you need the context of the request also? When you follow some <link rel="/featured-product" href="/products/3776"/> link and the servers sends an HTML page back do you understand the meaning of the steady state from looking at the Content-Type header or do you add-in the information that the server told you the resource you just requested is 'the featured product'?


Another way to ask this is: When you bookmark /products/3776 and later go back to it, do you know it represents a product?

Or: If you send your friend the link: /products/3776, do you say "Check this out" or "Check this cool product out"?

And, when you receive "Check out /products/3776" do you know /products/3776 represents a product when you look at the representation?

jan


> 
> 
> 
> > As to the issue of steady-states, consider the browser.  The user
> > follows one link, but the next steady-state may only be achieved by
> > dereferencing pertinent URIs within the initial representation.  Your
> > post implies that there's a 1:1 relationship between that initial
> > representation's retrieval and the next steady-state.
> 
> No. At least I did not want to imply that. The steady state is reached when all the outstanding sub-requests have been made and then, when the client has no pending requests - on what basis does it determine the meaning of the state?
> 
> In a machine client this would mean: "what information is taken into account to determine the next transition to follow? Just the media types of the steady state or also the context of the request?
> 
> Jan
> 
> > 
> > -Eric
> > 
> > "algermissen1971" wrote:
> > >
> > > When a client is in a steady state, what makes up the meaning of the
> > > state (what information does the client use to determine the meaning)?
> > > 
> > > a) The current representation (plus the understanding of the media
> > > types) b) The current representation (plus the understanding of the
> > > media types) and the request the client made (the knowledge of the
> > > semantics of the resource that the representation has been obtained
> > > from) c) b) and knowledge about all the requests it made before (this
> > > is wrong from a REST POV, but I include it for completeness)
> > > 
> > > Note that b) includes knowledge about any conneg that might have
> > > happened. E.g. the client might have asked for
> > > 
> > >  GET /products/6676
> > >  Accept: application/xhtml
> > > +xml;profile="http://foo.org/my-html-product-representation-uformats-profile
> > > 
> > > and the server might have just answered with
> > > 
> > >  200 Ok
> > >  Content-Type: application/xhtml+xml
> > > 
> > > knowing that it serves the requested profile. (it did not say: your
> > > request for HTML with tht profile is 406 Not Acceptable). From the
> > > pure representation it is not detectable that the server sent this as
> > > a response to a request for 'a product representation'
> > > 
> > > 
> > > My understanding is b) but I am not entirely sure.
> > > 
> > > 
> > > Jan
> > > 
> > > 
> > >
> >
>

algermissen1971 wrote:
> When a client is in a steady state, what makes up the meaning of the state (what information does the client use to determine the meaning)?
>
> a) The current representation (plus the understanding of the media types)
> b) The current representation (plus the understanding of the media types) and the request the client made (the knowledge of the semantics of the resource that the representation has been obtained from)
> c) b) and knowledge about all the requests it made before (this is wrong from a REST POV, but I include it for completeness)
>   

Why is c necessarily wrong from a REST POV?

I would say the 'meaning' of the state is derived from the path taken 
through the flow of your hypertext-driven application, so it would 
include all state transitions taken from a given 'entry point' in your 
application.

- Mike

--- In rest-discuss@yahoogroups.com, Mike Kelly <mike@...> wrote:
>
> algermissen1971 wrote:
> > When a client is in a steady state, what makes up the meaning of the state (what information does the client use to determine the meaning)?
> >
> > a) The current representation (plus the understanding of the media types)
> > b) The current representation (plus the understanding of the media types) and the request the client made (the knowledge of the semantics of the resource that the representation has been obtained from)
> > c) b) and knowledge about all the requests it made before (this is wrong from a REST POV, but I include it for completeness)
> >   
> 
> Why is c necessarily wrong from a REST POV?

Because the meaning of a given state in a RESTful application does not depend on whatever happened before.

For example, consider an IO library where you need to remember that you opened a file. You read the next chunk, knowing it is still open, not because the state of the file descriptor provides a transition that lets you read a chunk. With REST you do not have a priori knowledge about the state the service (the file descriptor) goes through. You can understand each state in isolation.

Jan


> 
> I would say the 'meaning' of the state is derived from the path taken 
> through the flow of your hypertext-driven application, so it would 
> include all state transitions taken from a given 'entry point' in your 
> application.
> 
> - Mike
>

algermissen1971 wrote:
> --- In rest-discuss@yahoogroups.com, Mike Kelly <mike@...> wrote:
>   
>> algermissen1971 wrote:
>>     
>>> When a client is in a steady state, what makes up the meaning of the state (what information does the client use to determine the meaning)?
>>>
>>> a) The current representation (plus the understanding of the media types)
>>> b) The current representation (plus the understanding of the media types) and the request the client made (the knowledge of the semantics of the resource that the representation has been obtained from)
>>> c) b) and knowledge about all the requests it made before (this is wrong from a REST POV, but I include it for completeness)
>>>   
>>>       
>> Why is c necessarily wrong from a REST POV?
>>     
>
> Because the meaning of a given state in a RESTful application does not depend on whatever happened before.
>   

The client/application state.. ?

I'm not so sure given that 'hypertext is the engine of application 
state' - the only way for the client to understand the 'meaning' of its 
current state is in the context of the application flow (i.e. series of 
link relations) which led up to it.

- Mike

(response to off-list message about off-list messages and rest-discuss)
I had the same problem here, I forgot how I solved it, but now I can't
use the Web interface -- only e-mail -- to post to rest-discuss.  I
wish I could remember, seeing as how you're stuck with the opposite.

I'm going to hold off on answering your question until I have the demo
I've been working on furiously for the past two weeks, posted.  It
addresses a variety of issues regarding REST, Xforms, and client-side
XSLT.  Due to the demo's nature as client-side XSLT, I'm wearing my
application logic on my sleeve as hypertext (which goes beyond the
hypertext constraint, as opposed to breaking said constraint).

The application logic, whether the XSLT transformation is run on the
client or the server, is entirely based on link relations.  In fact,
the easiest part of distilling out a static example from my dynamic
project, turned out to be dismantling content negotiation.  All I did
was edit my Atom source files' link relation @hrefs by adding filename
extensions.  Which frees the demo up to run a directory browser so you
can introspect my files, including the content of dot files.

Since the application logic is based on link relations, changing the
URLs in the source Atom files also changed the URLs in the XHTML output
without my having to change the XSLT stylesheet.  I think my demo will
answer a lot of the questions you've been asking lately about machine
clients, or at least give you plenty of food for thought.

Bear with for a few days, I almost posted it already but I've torn the
httpd apart again... the httpd running the demo is a FOSS project I've
adopted and adapted to be a prototyping framework for REST development.
The source code for the httpd is posted as part of the demo.  Mostly not
my httpd code, but everything else is, save a line of XSLT and an XPATH
statement my partner contributed when I got stuck.

While it looks like the same demo I've been posting occasionally for 3
1/2 years, there came a point where I took off my architect hat and
decided to write the damn code myself, after failing to explain to many
different coders how to base application logic on link relations.  I'll
put my markup and CSS up against anyone's, and with more practice I'll
be saying that about my XSLT as well.  This should lay to rest the
recurring concerns about my skillz every time I try to contribute
something of my knowledge (Web developer since Dec. 1993) somewhere.

Like yesterday on www-tag when I was more-or-less accused of inventing
the Content-Script-Type header, in response to my polite suggestion that
it be considered within the context of an ongoing discussion.  Sigh.
Of course, my demo implements said header, and shows just exactly how
it can be used to solve the issue of distinguishing between scripted
and unscripted (X)HTML, and the issue of privilege escalation that I'm
patiently trying to explain to w3c folks where media type identifiers
other than text/plain are concerned.

Jan, I really should point out that you're saying "media type" where
you really mean "media type identifier", but the two are not the same
thing.  I've only recently decided that pointing this out isn't nit-
picking, but crucial to understanding Web architecture (which REST is a
subset of).  Anyway, I'll save my elaboration on why media type
identifers only describe containers, for some other time.  You're
leaning in a direction I reject out of hand, which is that a media type
identifier is a contract.  Contracts reside within the containers.

-Eric

(response to off-list message about off-list messages and rest-discuss)
I had the same problem here, I forgot how I solved it, but now I can't
use the Web interface -- only e-mail -- to post to rest-discuss.  I
wish I could remember, seeing as how you're stuck with the opposite.

I'm going to hold off on answering your question until I have the demo
I've been working on furiously for the past two weeks, posted.  It
addresses a variety of issues regarding REST, Xforms, and client-side
XSLT.  Due to the demo's nature as client-side XSLT, I'm wearing my
application logic on my sleeve as hypertext (which goes beyond the
hypertext constraint, as opposed to breaking said constraint).

The application logic, whether the XSLT transformation is run on the
client or the server, is entirely based on link relations.  In fact,
the easiest part of distilling out a static example from my dynamic
project, turned out to be dismantling content negotiation.  All I did
was edit my Atom source files' link relation @hrefs by adding filename
extensions.  Which frees the demo up to run a directory browser so you
can introspect my files, including the content of dot files.

Since the application logic is based on link relations, changing the
URLs in the source Atom files also changed the URLs in the XHTML output
without my having to change the XSLT stylesheet.  I think my demo will
answer a lot of the questions you've been asking lately about machine
clients, or at least give you plenty of food for thought.

Bear with for a few days, I almost posted it already but I've torn the
httpd apart again... the httpd running the demo is a FOSS project I've
adopted and adapted to be a prototyping framework for REST development.
The source code for the httpd is posted as part of the demo.  Mostly not
my httpd code, but everything else is, save a line of XSLT and an XPATH
statement my partner contributed when I got stuck.

While it looks like the same demo I've been posting occasionally for 3
1/2 years, there came a point where I took off my architect hat and
decided to write the damn code myself, after failing to explain to many
different coders how to base application logic on link relations.  I'll
put my markup and CSS up against anyone's, and with more practice I'll
be saying that about my XSLT as well.  This should lay to rest the
recurring concerns about my skillz every time I try to contribute
something of my knowledge (Web developer since Dec. 1993) somewhere.

Like yesterday on www-tag when I was more-or-less accused of inventing
the Content-Script-Type header, in response to my polite suggestion that
it be considered within the context of an ongoing discussion.  Sigh.
Of course, my demo implements said header, and shows just exactly how
it can be used to solve the issue of distinguishing between scripted
and unscripted (X)HTML, and the issue of privilege escalation that I'm
patiently trying to explain to w3c folks where media type identifiers
other than text/plain are concerned.

Jan, I really should point out that you're saying "media type" where
you really mean "media type identifier", but the two are not the same
thing.  I've only recently decided that pointing this out isn't nit-
picking, but crucial to understanding Web architecture (which REST is a
subset of).  Anyway, I'll save my elaboration on why media type
identifers only describe containers, for some other time.  You're
leaning in a direction I reject out of hand, which is that a media type
identifier is a contract.  Contracts reside within the containers.

-Eric

Sorry for the double-post, list.  I think y'all know how it goes with
rest-discuss posting some days, right?  ;-)

-Eric

On Jan 24, 2010, at 2:07 PM, Mike Kelly wrote:

> the only way for the client to understand the 'meaning' of its  
> current state is in the context of the application flow (i.e. series  
> of link relations) which led up to it.


Correct me, but this is exactly what REST prevents. A client can use  
the URI of any steady-state and just proceed through the application  
from that point on without the need for any knowledge about prior  
interactions. If it can't, the representation is just badly designed.

(Which makes a nice principle for media type design)

Jan




-----------------------------------
  Jan Algermissen, Consultant

  Mail: algermissen@...
  Blog: http://www.nordsc.com/blog/
  Work: http://www.nordsc.com/
-----------------------------------

I have a representation with a collection, each item of the collection
has a rel="itself" link targeting its details representation....

example:

the collection:      http://fgaucho.dyndns.org:8080/arena-http/competition

following the itself link:
http://fgaucho.dyndns.org:8080/arena-http/competition/_1929737737

Question: in this second URI, the link should disappear ?

* I am trying to map the state of the resources direct in the
database, and that's why the question. It is hard to make it truly
dynamic in the database.. and I hate to waste server time adding and
removing links to the resource representations :)
* It is possible to have a second lits in the sub-resource table in
the database, basically with the same links but with different names
just to fit the style..........

-- 
------------------------------------------
   Felipe Ga�cho
   10+ Java Programmer
   CEJUG Senior Advisor

Jan Algermissen wrote:
> On Jan 24, 2010, at 2:07 PM, Mike Kelly wrote:
>
>   
>> the only way for the client to understand the 'meaning' of its  
>> current state is in the context of the application flow (i.e. series  
>> of link relations) which led up to it.
>>     
>
>
> Correct me, but this is exactly what REST prevents. A client can use  
> the URI of any steady-state and just proceed through the application  
> from that point on without the need for any knowledge about prior  
> interactions. If it can't, the representation is just badly designed.
>   

Are we drawing a distinction here between steady-state and entry-point? 
 From my understanding - you are describing the latter, but not 
necessarily the former.

I'm thinking purely from a client perspective. A server shouldn't be 
aware of any such 'context' since there is no shared state.

- Mike

On Jan 24, 2010, at 4:46 PM, Mike Kelly wrote:

> Jan Algermissen wrote:
>> On Jan 24, 2010, at 2:07 PM, Mike Kelly wrote:
>>
>>
>>> the only way for the client to understand the 'meaning' of its   
>>> current state is in the context of the application flow (i.e.  
>>> series  of link relations) which led up to it.
>>>
>>
>>
>> Correct me, but this is exactly what REST prevents. A client can  
>> use  the URI of any steady-state and just proceed through the  
>> application  from that point on without the need for any knowledge  
>> about prior  interactions. If it can't, the representation is just  
>> badly designed.
>>
>
> Are we drawing a distinction here between steady-state and entry- 
> point?

Hmm, IMHO each steady state is a potential entry point.

Jan


> From my understanding - you are describing the latter, but not  
> necessarily the former.
>
> I'm thinking purely from a client perspective. A server shouldn't be  
> aware of any such 'context' since there is no shared state.
>
> - Mike

-----------------------------------
  Jan Algermissen, Consultant

  Mail: algermissen@...
  Blog: http://www.nordsc.com/blog/
  Work: http://www.nordsc.com/
-----------------------------------

On Jan 24, 2010, at 4:22 PM, Felipe Ga�cho wrote:

> I have a representation with a collection, each item of the collection
> has a rel="itself" link targeting its details representation....
>
> example:
>
> the collection:      http://fgaucho.dyndns.org:8080/arena-http/competition
>
> following the itself link:
> http://fgaucho.dyndns.org:8080/arena-http/competition/_1929737737

Do you mean rel="self"?

>
> Question: in this second URI, the link should disappear ?

Do you mean in the representation of the entry? That's up to you. It  
might be useful in scenarios where the entry XML ends up on disk (when  
you loose the request URI) then the self tells you where the entry XML  
came from.


>
> * I am trying to map the state of the resources direct in the
> database, and that's why the question. It is hard to make it truly
> dynamic in the database..

In my experience, it is often a waste of time to try to be very  
dynamic/general/automatic. Just ask the underlying DAO for the data  
and pupulate the Atom entry object 'by hand'. That's fine.

> and I hate to waste server time adding and
> removing links to the resource representations :)

Hmm - are you sure populating another XML element is significant in a  
networked environment (the network call consuming orders of magnitude  
more CPU cycles than adding the element)?


> * It is possible to have a second lits in the sub-resource table in
> the database, basically with the same links but with different names
> just to fit the style..........

Do not understand. Can you explain?

HTH,

Jan


>
> -- 
> ------------------------------------------
>   Felipe Ga�cho
>   10+ Java Programmer
>   CEJUG Senior Advisor
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

-----------------------------------
  Jan Algermissen, Consultant

  Mail: algermissen@...
  Blog: http://www.nordsc.com/blog/
  Work: http://www.nordsc.com/
-----------------------------------

On Jan 24, 2010, at 4:51 PM, Jan Algermissen wrote:

>
> On Jan 24, 2010, at 4:46 PM, Mike Kelly wrote:
>
>> Jan Algermissen wrote:
>>> On Jan 24, 2010, at 2:07 PM, Mike Kelly wrote:
>>>
>>>
>>>> the only way for the client to understand the 'meaning' of its
>>>> current state is in the context of the application flow (i.e.
>>>> series  of link relations) which led up to it.
>>>>
>>>
>>>
>>> Correct me, but this is exactly what REST prevents. A client can
>>> use  the URI of any steady-state and just proceed through the
>>> application  from that point on without the need for any knowledge
>>> about prior  interactions. If it can't, the representation is just
>>> badly designed.
>>>
>>
>> Are we drawing a distinction here between steady-state and entry-
>> point?
>
> Hmm, IMHO each steady state is a potential entry point.

I knew it wasn't my clever observation but that Roy wrote it  
somewhere... here is the link:
<http://tech.groups.yahoo.com/group/rest-discuss/message/5841>

Jan




>
> Jan
>
>
>> From my understanding - you are describing the latter, but not
>> necessarily the former.
>>
>> I'm thinking purely from a client perspective. A server shouldn't be
>> aware of any such 'context' since there is no shared state.
>>
>> - Mike
>
> -----------------------------------
>  Jan Algermissen, Consultant
>
>  Mail: algermissen@...
>  Blog: http://www.nordsc.com/blog/
>  Work: http://www.nordsc.com/
> -----------------------------------
>
>
>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

-----------------------------------
  Jan Algermissen, Consultant

  Mail: algermissen@...
  Blog: http://www.nordsc.com/blog/
  Work: http://www.nordsc.com/
-----------------------------------

> Do you mean rel="self"?

yes... more and less.. because it is inspired in the atom pub but it
is not atom pub.. it is my domain specific link...

I eventually can use atom instead of a proprietary one.. but in
general my application doesn't use atom ........


> Do you mean in the representation of the entry? That's up to you. It might
> be useful in scenarios where the entry XML ends up on disk (when you loose
> the request URI) then the self tells you where the entry XML came from.

ok.......

> In my experience, it is often a waste of time to try to be very dynamic/general/automatic. Just ask the underlying DAO for the data and pupulate the Atom entry object 'by hand'. That's fine.

the problem here is: to maintain a large amount of code just to do
this copies .. it seems fine in a small example, but for hundreds of
entities that eventually  will be modified in the future is a mess to
have copy and transformations between the DAo and the HTTP layer......
I created a small framework to traverse the data without extra
processing....


> Hmm - are you sure populating another XML element is significant in a networked environment ...

not significant in terms of processing, but for sure in terms of
software maintenance...


> Do not understand. Can you explain?


I have an entity with a collection field. and I have a sub-entity that
inherits the collection from its parent. I can eventually have a
second collection in the subclass, overwriting the parent one, just
for changing the names.. but I am now see it will add more problems
than solutions..

thanks for the tips..........

* after the presentation at Jfokus I will publish the slides and also
some blogs to show what I have here.. for now I am still focusing in a
good presentation at Stockholm...

any of you at Jfokus, Sweden this week, please tell me and we can
share a beer or two over REST topic :)

On Jan 24, 2010, at 7:10 PM, Felipe Ga�cho wrote:

>> Do you mean rel="self"?
>
> yes... more and less.. because it is inspired in the atom pub but it
> is not atom pub.. it is my domain specific link...
>

You can use 'self' even if you do not use Atom. Link relations are  
independent of the kind of representation they occur in.


> I eventually can use atom instead of a proprietary one.. but in
> general my application doesn't use atom ........
>
>
>> Do you mean in the representation of the entry? That's up to you.  
>> It might
>> be useful in scenarios where the entry XML ends up on disk (when  
>> you loose
>> the request URI) then the self tells you where the entry XML came  
>> from.
>
> ok.......
>
>> In my experience, it is often a waste of time to try to be very  
>> dynamic/general/automatic. Just ask the underlying DAO for the data  
>> and pupulate the Atom entry object 'by hand'. That's fine.
>
> the problem here is: to maintain a large amount of code just to do
> this copies .. it seems fine in a small example, but for hundreds of
> entities that eventually  will be modified in the future is a mess to
> have copy and transformations between the DAo and the HTTP layer......

Factor out a super class...

> I created a small framework to traverse the data without extra
> processing....
>
>
>> Hmm - are you sure populating another XML element is significant in  
>> a networked environment ...
>
> not significant in terms of processing, but for sure in terms of
> software maintenance...
>
>
>> Do not understand. Can you explain?
>
>
> I have an entity with a collection field. and I have a sub-entity that
> inherits the collection from its parent. I can eventually have a
> second collection in the subclass, overwriting the parent one, just
> for changing the names.. but I am now see it will add more problems
> than solutions..
>
> thanks for the tips..........
>
> * after the presentation at Jfokus I will publish the slides and also
> some blogs to show what I have here.. for now I am still focusing in a
> good presentation at Stockholm...

Good luck.

>
> any of you at Jfokus, Sweden this week, please tell me and we can
> share a beer or two over REST topic :)
>

Thanks, but, sorry, I am not there..

Jan





>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

-----------------------------------
  Jan Algermissen, Consultant

  Mail: algermissen@...
  Blog: http://www.nordsc.com/blog/
  Work: http://www.nordsc.com/
-----------------------------------

>
>
> > * I am trying to map the state of the resources direct in the
> > database, and that's why the question. It is hard to make it truly
> > dynamic in the database..
>
You can use non-sql databases which are -usually- better suited for dynamic
structures.

 In my experience, it is often a waste of time to try to be very
> dynamic/general/automatic. Just ask the underlying DAO for the data
> and pupulate the Atom entry object 'by hand'. That's fine.
>
I partially agree here: while default behavior is overriden in a lot of
applications, if well thought of, it can be used out of the box without much
of a config: i.e. XStream's defaults were a mark on xml serialization
libraries history for Java.

Regards

> You can use non-sql databases which are -usually- better suited for dynamic structures.

You mean OO db ? I evaluated that option, but unfortunately the
community around such tools is too small  :) but it is always an
option....

The point here is not how you persist the data but how you change it
on the fly... (unless I can have wildcards in a type of database)


> I partially agree here: while default behavior is overriden in a lot of applications, if well thought of, it can be used out of the box without much of a config: i.e. XStream's defaults were a mark on xml serialization libraries history for Java.

please point to an example...

my current code for reading a resource:

@Override
@TransactionAttribute(TransactionAttributeType.NOT_SUPPORTED)
public T read(Class<T> type, final Object primaryKey)
		throws IllegalStateException, IllegalArgumentException {
	return manager.find(type, primaryKey);
}

and the code to expose it on the web:

@GET
@Produces( { MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
@Path("{name}")
public PujCompetitionDetailsEntity read(@PathParam("name") String name) {
	return detailsFacade.read(PujCompetitionDetailsEntity.class, name);
}

Thanks for all the replies.

(I tried to post a follow up message but for some reason it did not make it on the list. Probably messed up somehow)

So, I agree (obviously) that it is more an implementation problem than a architectural one.

That said, eventually architectures expose most of their value by being implemented :), so to rephrase my question, does anyone have any pointers to information that deals with implementing fine grained authorization at the REST level. Environment is not relevant right now for me as I am just trying to graps possible abstrations that make sense in this context.

Personally I am trying to get something going by combining JSR311 with Spring security but it gets a bit hairy if one wants to keep authorization as a cross cutting concern that is mainly specified declaratively. 

Furthermore, I don't have a good way of coping with e.g. a PUT of a resource where an attribute is not provided. How to distinguish an attempt to 'nullify' that attribute vs a client that is PUTting the resource without having access to the resource and at the same time keeping the authorization code out of the REST processing logic.


Any help warmly appreciated!

Peter


--- In rest-discuss@yahoogroups.com, Jim Webber <jim@...> wrote:
>
> Hi Peter,
> 
> Will's right when he says "REST" has nothing to with this. But there are regular ways of dealing with this using HTTP.
> 
> > - The price of a given order item should be 'readable' by the 'creator' of the order item while an 'administrator' should be able to update the price
> 
> Using one of the HTTP authentication mechanisms (or OpenID, OAuth even) the creator will happily receive 401 when applying some verbs (e.g. PUT, DELETE) to a resource (e.g. pricing) but find they're get 200 OK responses to other verbs (e.g. GET). The administrator might find they receive 200 OK responses to all of those operations.
> 
> > - An collection of order states (not a separate resource but part of the order) should be readable by the 'creator'. An 'administrator' should be able to add states
> 
> How the order is projected onto the Web in terms of resources is an implementation decision. You might choose to have the collection of order states physically written down on the same piece of paper in your back end, but you could still happily project them as different logical resources onto the Web. Hypermedia is your friend should you want to link them together. Eg:
> 
> Administrator: GET/order/1234
> 200 OK....
> <order>
> <atom:link href="http://myservice/order/1234/state" rel="order-state" type="application/x.ordering+xml"/>
> <line-item> ... </lineItem>
> </order>
> 
> Creator: GET/order/1234
> 200 OK...
> <order>
> <line-item> ... </lineItem>
> </order>
> 
> Creator, after some creative thought tries: GET http://myservice/order/1234/state
> 401 Unauthorized...
> 
> Nonetheless, administrators will have more chance of a 200 OK response than creators just as above.
> 
> Does that help at all?
> 
> Jim
>

> please point to an example...
Convention over Configuration: Erlang's OTP imply on default function names
in order to work, otherwise you have to work it on your own. Rails is the
best example, being used around with a lot of conventions.

For the Java platform, Restfulie follows this path in the controller: the
same JAX-RS code you have mentioned in restfulie java could be to:

public T read(Object key) {
  return manager.find(key);
}

public T retrieve(T object) {
  return dao.read(object.getPrimaryKey());
}


Of couse, it depends on a lot of conventions - but they made your code much
simpler:
a) the dao object knows how to generic handle types
b) the controller methods that know how to handle resources have some
default names (retrieve, update, create, delete, head, ...)

All of this can be implemented - including removing both methods and
requiring zero code for this specific behavior, if thats the conventional
one.

cheers

Guilherme Silveira
Caelum | Ensino e Inova��o
http://www.caelum.com.br/


my current code for reading a resource:
>
> @Override
> @TransactionAttribute(TransactionAttributeType.NOT_SUPPORTED)
> public T read(Class<T> type, final Object primaryKey)
> throws IllegalStateException, IllegalArgumentException {
> return manager.find(type, primaryKey);
> }
>
> and the code to expose it on the web:
>
> @GET
> @Produces( { MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
> @Path("{name}")
> public PujCompetitionDetailsEntity read(@PathParam("name") String name) {
> return detailsFacade.read(PujCompetitionDetailsEntity.class, name);
> }
>
>  
>

Hi all,

As Jan suggested in the previous post http://tech.groups.yahoo.com/group/rest-discuss/message/14627, let's use the REST wiki for collecting interesting REST-related links and distribute them on a weekly basis. 

There are currently two wiki pages:
1. The list of all weekly summaries on http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly. Every week on Monday, I (or someone else) will create a new page for that week and add it to the list.
2. The wiki page for this week is on http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Jan_25_2010

So, if we find anything REST-related worth reading - just add a link to the wiki page and I'll post the links to this group when the week is over, and perhaps create a blog for feed-based distribution.

Cheers!
Ivan

just for curiosity... (if you posted a real code)....

- the code is digesting the exceptions ??
- how your code knows the return type (json, xml, xhtml, etc)?

as fair I see this are the only difference between the two codes..

* yes, I can use that trick to inspect the generic type, but I preferred to
pass as reference due to other purposes ...


2010/1/25 Guilherme Silveira <guilherme.silveira@...>

> > please point to an example...
> Convention over Configuration: Erlang's OTP imply on default function names
> in order to work, otherwise you have to work it on your own. Rails is the
> best example, being used around with a lot of conventions.
>
> For the Java platform, Restfulie follows this path in the controller: the
> same JAX-RS code you have mentioned in restfulie java could be to:
>
> public T read(Object key) {
>   return manager.find(key);
> }
>
> public T retrieve(T object) {
>   return dao.read(object.getPrimaryKey());
> }
>
>
> Of couse, it depends on a lot of conventions - but they made your code much
> simpler:
> a) the dao object knows how to generic handle types
> b) the controller methods that know how to handle resources have some
> default names (retrieve, update, create, delete, head, ...)
>
> All of this can be implemented - including removing both methods and
> requiring zero code for this specific behavior, if thats the conventional
> one.
>
> cheers
>
> Guilherme Silveira
> Caelum | Ensino e Inova��o
> http://www.caelum.com.br/
>
>
> my current code for reading a resource:
>>
>> @Override
>> @TransactionAttribute(TransactionAttributeType.NOT_SUPPORTED)
>> public T read(Class<T> type, final Object primaryKey)
>> throws IllegalStateException, IllegalArgumentException {
>> return manager.find(type, primaryKey);
>> }
>>
>> and the code to expose it on the web:
>>
>> @GET
>> @Produces( { MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
>> @Path("{name}")
>> public PujCompetitionDetailsEntity read(@PathParam("name") String name) {
>> return detailsFacade.read(PujCompetitionDetailsEntity.class, name);
>> }
>>
>>  
>>
>
>


-- 
------------------------------------------
  Felipe Ga�cho
  10+ Java Programmer
  CEJUG Senior Advisor

Hello Felipe!

- the code is digesting the exceptions ??
RuntimeExceptions are hidden there

- how your code knows the return type (json, xml, xhtml, etc)?
Content-negotiation, the server knows which types it can handle..

Regards

Guilherme Silveira
Caelum | Ensino e Inova��o
http://www.caelum.com.br/


2010/1/25 Felipe Ga�cho <fgaucho@...>

>
>
> just for curiosity... (if you posted a real code)....
>
> - the code is digesting the exceptions ??
> - how your code knows the return type (json, xml, xhtml, etc)?
>
> as fair I see this are the only difference between the two codes..
>
> * yes, I can use that trick to inspect the generic type, but I preferred to
> pass as reference due to other purposes ...
>
>
> 2010/1/25 Guilherme Silveira <guilherme.silveira@...>
>
> > please point to an example...
>> Convention over Configuration: Erlang's OTP imply on default function
>> names in order to work, otherwise you have to work it on your own. Rails is
>> the best example, being used around with a lot of conventions.
>>
>> For the Java platform, Restfulie follows this path in the controller: the
>> same JAX-RS code you have mentioned in restfulie java could be to:
>>
>> public T read(Object key) {
>>   return manager.find(key);
>> }
>>
>> public T retrieve(T object) {
>>   return dao.read(object.getPrimaryKey());
>> }
>>
>>
>> Of couse, it depends on a lot of conventions - but they made your code
>> much simpler:
>> a) the dao object knows how to generic handle types
>> b) the controller methods that know how to handle resources have some
>> default names (retrieve, update, create, delete, head, ...)
>>
>> All of this can be implemented - including removing both methods and
>> requiring zero code for this specific behavior, if thats the conventional
>> one.
>>
>> cheers
>>
>> Guilherme Silveira
>> Caelum | Ensino e Inova��o
>> http://www.caelum.com.br/
>>
>>
>>  my current code for reading a resource:
>>>
>>> @Override
>>> @TransactionAttribute(TransactionAttributeType.NOT_SUPPORTED)
>>> public T read(Class<T> type, final Object primaryKey)
>>> throws IllegalStateException, IllegalArgumentException {
>>> return manager.find(type, primaryKey);
>>> }
>>>
>>> and the code to expose it on the web:
>>>
>>> @GET
>>> @Produces( { MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
>>> @Path("{name}")
>>> public PujCompetitionDetailsEntity read(@PathParam("name") String name) {
>>> return detailsFacade.read(PujCompetitionDetailsEntity.class, name);
>>> }
>>>
>>>
>>
>
>
> --
> ------------------------------------------
>   Felipe Ga�cho
>   10+ Java Programmer
>   CEJUG Senior Advisor
>
>  
>

> - the code is digesting the exceptions ??
> RuntimeExceptions are hidden there


ok, but what is returned to the client in case of such exceptions  ?

- how your code knows the return type (json, xml, xhtml, etc)?

> Content-negotiation, the server knows which types it can handle..
>

ok, like default Jersey.. (annotating XML and JSON for Jersey is redundant..
but I got this habit of including the annotations explicitly anyway.. I just
type them without thinking if I should or not..  :) .. there is a lot o
unecessary annotations in my code, a way of keeping myself aware  about the
code surroundings......

Restfulie sounds pretty cool.. and, how about the hateoas ? the dynamic part
...

how to add or remove links from the representations ? is it done
programatically ?

On Jan 25, 2010, at 7:18 AM, Felipe Ga�cho wrote:

> @GET
> @Produces( { MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })

As a side note (in order to promote RESTful REST):

You should not use application/xml or application/json because these  
violate REST's message self descriptiveness constraint (unless you  
really only want to transfer XML or JSON without any additional, out- 
of-band semantics).

Instead, use specific media types (even if you have to mint your own)  
or at least use a profile parameter[1] on the generic media type to  
put the out-of-band information in-band.


> @Path("{name}")
> public PujCompetitionDetailsEntity read(@PathParam("name") String  
> name) {
> 	return detailsFacade.read(PujCompetitionDetailsEntity.class, name);
> }


Jan


[1] <http://tech.groups.yahoo.com/group/rest-discuss/message/14612>




-----------------------------------
  Jan Algermissen, Consultant

  Mail: algermissen@...
  Blog: http://www.nordsc.com/blog/
  Work: http://www.nordsc.com/
-----------------------------------

yes, yes, I learned that recently and I plan to change the plain:

application/xml

for something like:

application/arena+xml



2010/1/25 Jan Algermissen <algermissen1971@...>:
>
> On Jan 25, 2010, at 7:18 AM, Felipe Ga�cho wrote:
>
>> @GET
>> @Produces( { MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
>
> As a side note (in order to promote RESTful REST):
>
> You should not use application/xml or application/json because these violate
> REST's message self descriptiveness constraint (unless you really only want
> to transfer XML or JSON without any additional, out-of-band semantics).
>
> Instead, use specific media types (even if you have to mint your own) or at
> least use a profile parameter[1] on the generic media type to put the
> out-of-band information in-band.
>
>
>> @Path("{name}")
>> public PujCompetitionDetailsEntity read(@PathParam("name") String name) {
>> � � � �return detailsFacade.read(PujCompetitionDetailsEntity.class, name);
>> }
>
>
> Jan
>
>
> [1] <http://tech.groups.yahoo.com/group/rest-discuss/message/14612>
>
>
>
>
> -----------------------------------
> �Jan Algermissen, Consultant
>
> �Mail: algermissen@...
> �Blog: http://www.nordsc.com/blog/
> �Work: http://www.nordsc.com/
> -----------------------------------
>
>
>
>



-- 
------------------------------------------
   Felipe Ga�cho
   10+ Java Programmer
   CEJUG Senior Advisor

--- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
>
> 
> On Jan 24, 2010, at 4:51 PM, Jan Algermissen wrote:
> 
> >
> > On Jan 24, 2010, at 4:46 PM, Mike Kelly wrote:
> >
> >> Jan Algermissen wrote:
> >>> On Jan 24, 2010, at 2:07 PM, Mike Kelly wrote:
> >>>
> >>>
> >>>> the only way for the client to understand the 'meaning' of its
> >>>> current state is in the context of the application flow (i.e.
> >>>> series  of link relations) which led up to it.
> >>>>
> >>>
> >>>
> >>> Correct me, but this is exactly what REST prevents. A client can
> >>> use  the URI of any steady-state and just proceed through the
> >>> application  from that point on without the need for any knowledge
> >>> about prior  interactions. If it can't, the representation is just
> >>> badly designed.
> >>>
> >>
> >> Are we drawing a distinction here between steady-state and entry-
> >> point?
> >
> > Hmm, IMHO each steady state is a potential entry point.
> 
> I knew it wasn't my clever observation but that Roy wrote it  
> somewhere... here is the link:
> <http://tech.groups.yahoo.com/group/rest-discuss/message/5841>
> 

Another relevant Roy writing (wow this list feels like theological discussions referencing Bible passages sometimes!) is in section 6.3.4.2 of his thesis where he talks about cookies messing up the back button. 

Your application state machine should allow arbitrary jumps (via "typed in" urls, back buttons, etc.) and so that implies that the application state shouldn't depend on the path taken.

At the same time I can think there is "client state" that is independent of "application state". For example, the size of the window in a browser, the content that an atompub client is trying to publish are some examples. This client state affects the execution of the application, combining with the application state to affect client behavior. e.g. the application could display differently depending on the window size or the atompub client could pick different feeds from the service doc based on client state.

I think was is important is that the application state should never rely on the client state value. One possible approach to ensuring this is to enforce that the application state should never affect/change the client state, but I don't think this is necessary or realistic. For example, the content that a client is trying to publish might depend on something that it previously fetched. The HTML5 client-side SQL store is another example of mutable client state (I think).

So I think that application state can effect the client state, but as long as your application states never depend on the client state, you can jump around to arbitrary application states without things breaking. This does constrain how you do things though, for example, you have to write your HTML5 application to not depend on the state of client-side SQL tables.

I'm making up my own terminology here as I'm not aware of a precedent. And maybe, this "client state" is really part of the application state -- but that doesn't seem right to me and doesn't match my experience.
Regards,

Andrew

Andrew:

I treat client state as volatile optional data - similar to cached
data. IOW, I write my code to work w/ any existing client state if
it's available and, if not, lead the client into creating the needed
state to complete the operation.

Shopping cart is an example. When I client visits a URI, the server
might check to see if there is any client state data (stored
selections in the cart) to display. If not, the client is offered the
proper link(s) to create some cart data.

If I have any multiple-step operations (ala "Wizard UI") I'll inspect
the client state on each step to see where in the process they
currently are. If no state is avail (or some of the data is missing or
has expired), the client is directed to the proper URI (possibly the
start URI) and led along as needed.

If a client attempts a write operation on the server (POST/PUT)
without the required client state data (missing or invalid state
data), the client is given the appropriate response code and offered
one or more URIs to help deliver the expected data before
re-attempting the write operation.

The "client state data" might be complete data on the client (for
custom clients) or a cookie identifier/authentication identifier (for
common Web browsers). In the case of common browsers, I store any
complex client state data on the server as a user resource (instead of
user-agent resource) to get around data storage limits in current
browsers and make sure users can log in via different agents and still
retrieve their data. Now that local data storage APIs are available
for scripted browsers, I hope to move some of this data back to the
client.

All these examples might include an authenticate step, but that's
treated as an additional layer on the set of state transitions.

In my experience, adopting these patterns from the outset takes more
implementation time, but results in a more stable and, in the long
run, more adaptable application.

mca
http://amundsen.com/blog/




On Mon, Jan 25, 2010 at 13:44, wahbedahbe <andrew.wahbe@...> wrote:
>
>
> --- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
>>
>>
>> On Jan 24, 2010, at 4:51 PM, Jan Algermissen wrote:
>>
>> >
>> > On Jan 24, 2010, at 4:46 PM, Mike Kelly wrote:
>> >
>> >> Jan Algermissen wrote:
>> >>> On Jan 24, 2010, at 2:07 PM, Mike Kelly wrote:
>> >>>
>> >>>
>> >>>> the only way for the client to understand the 'meaning' of its
>> >>>> current state is in the context of the application flow (i.e.
>> >>>> series �of link relations) which led up to it.
>> >>>>
>> >>>
>> >>>
>> >>> Correct me, but this is exactly what REST prevents. A client can
>> >>> use �the URI of any steady-state and just proceed through the
>> >>> application �from that point on without the need for any knowledge
>> >>> about prior �interactions. If it can't, the representation is just
>> >>> badly designed.
>> >>>
>> >>
>> >> Are we drawing a distinction here between steady-state and entry-
>> >> point?
>> >
>> > Hmm, IMHO each steady state is a potential entry point.
>>
>> I knew it wasn't my clever observation but that Roy wrote it
>> somewhere... here is the link:
>> <http://tech.groups.yahoo.com/group/rest-discuss/message/5841>
>>
>
> Another relevant Roy writing (wow this list feels like theological discussions referencing Bible passages sometimes!) is in section 6.3.4.2 of his thesis where he talks about cookies messing up the back button.
>
> Your application state machine should allow arbitrary jumps (via "typed in" urls, back buttons, etc.) and so that implies that the application state shouldn't depend on the path taken.
>
> At the same time I can think there is "client state" that is independent of "application state". For example, the size of the window in a browser, the content that an atompub client is trying to publish are some examples. This client state affects the execution of the application, combining with the application state to affect client behavior. e.g. the application could display differently depending on the window size or the atompub client could pick different feeds from the service doc based on client state.
>
> I think was is important is that the application state should never rely on the client state value. One possible approach to ensuring this is to enforce that the application state should never affect/change the client state, but I don't think this is necessary or realistic. For example, the content that a client is trying to publish might depend on something that it previously fetched. The HTML5 client-side SQL store is another example of mutable client state (I think).
>
> So I think that application state can effect the client state, but as long as your application states never depend on the client state, you can jump around to arbitrary application states without things breaking. This does constrain how you do things though, for example, you have to write your HTML5 application to not depend on the state of client-side SQL tables.
>
> I'm making up my own terminology here as I'm not aware of a precedent. And maybe, this "client state" is really part of the application state -- but that doesn't seem right to me and doesn't match my experience.
> Regards,
>
> Andrew
>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

On Jan 25, 2010, at 7:44 PM, wahbedahbe wrote:

> At the same time I can think there is "client state" that is  
> independent of "application state".

Yes. It is (part of) the state of the state machine that is the client- 
side program (or the human user). The interesting aspect here is what  
the appropriate programming model is for aligning the client side  
state machine and the user agent state machine (which is driven by the  
server).

The situation is comparable to a program that is not promarily driven  
by a GUI but occasionally hands control over to a GUI event processing  
loop.

Jan

-----------------------------------
  Jan Algermissen, Consultant

  Mail: algermissen@...
  Blog: http://www.nordsc.com/blog/
  Work: http://www.nordsc.com/
-----------------------------------

Felipe, you can also use media profiles:
http://buzzword.org.uk/2009/draft-inkster-profile-parameter-00.html

Guilherme Silveira
Caelum | Ensino e Inova��o
http://www.caelum.com.br/


2010/1/25 Felipe Ga�cho <fgaucho@gmail.com>

>
>
> yes, yes, I learned that recently and I plan to change the plain:
>
> application/xml
>
> for something like:
>
> application/arena+xml
>
> 2010/1/25 Jan Algermissen <algermissen1971@...<algermissen1971%40mac.com>
> >:
>
> >
> > On Jan 25, 2010, at 7:18 AM, Felipe Ga�cho wrote:
> >
> >> @GET
> >> @Produces( { MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
> >
> > As a side note (in order to promote RESTful REST):
> >
> > You should not use application/xml or application/json because these
> violate
> > REST's message self descriptiveness constraint (unless you really only
> want
> > to transfer XML or JSON without any additional, out-of-band semantics).
> >
> > Instead, use specific media types (even if you have to mint your own) or
> at
> > least use a profile parameter[1] on the generic media type to put the
> > out-of-band information in-band.
> >
> >
> >> @Path("{name}")
> >> public PujCompetitionDetailsEntity read(@PathParam("name") String name)
> {
> >>        return detailsFacade.read(PujCompetitionDetailsEntity.class,
> name);
> >> }
> >
> >
> > Jan
> >
> >
> > [1] <http://tech.groups.yahoo.com/group/rest-discuss/message/14612>
> >
> >
> >
> >
> > -----------------------------------
> >  Jan Algermissen, Consultant
> >
> >  Mail: algermissen@... <algermissen%40acm.org>
> >  Blog: http://www.nordsc.com/blog/
> >  Work: http://www.nordsc.com/
> > -----------------------------------
> >
> >
> >
> >
>
> --
> ------------------------------------------
> Felipe Ga�cho
> 10+ Java Programmer
> CEJUG Senior Advisor
>  
>

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
 
I was curious if there are opinions regarding the congruence of forms
(HTML <form>s) and links. It would seem to me that forms are an
important part of hypertext navigation, and could be characterized as
a user-input-parameterized link, at least with GET-based forms.
However, I was curious if others are in agreement on this perspective.
If a form is a type of link, why does HTML not define a "rel"
attribute for forms? OpenSearch [1] also defines navigation to URIs
that are parameterized by user-supplied data, but it does include
"rel" attribute. From a navigational perspective, is there any
fundamental difference between HTML form and OpenSearch links (other
than that HTML obviously prescribes more of the presentation aspect)?
If forms can be viewed as link mechanisms, should this only be applied
to GET-based forms, or can POST-driven user parametrized data also be
considered a form of a navigable link?

The reason I ask, is I am trying to feel out if the approach in JSON
schema, of allowing user-parametrized data submission [2] as an
extension of a link definition is appropriate. With this approach,
links can include additional information, extending them to take user
provided data to form URIs, and specify the request method. IMO, this
is an elegant way of minimizing constructs while still allowing for
URIs to be parameterized with user input like forms, but I wasn't sure
if others felt this would violate any principles of REST.

[1] http://www.opensearch.org/Specifications/OpenSearch/1.1
[2] http://tools.ietf.org/html/draft-zyp-json-schema-01#section-6.1.1.3

Thanks,

- -- 
Kris Zyp
SitePen
(503) 806-1841
http://sitepen.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
 
iEYEARECAAYFAktgkW0ACgkQ9VpNnHc4zAwykACdHO/ORNeFFy5g07rzy90MzPSr
zPMAoJmmg/UQJizuvys79ULqWfKTKmlY
=4uDy
-----END PGP SIGNATURE-----

On Jan 27, 2010, at 8:18 PM, Kris Zyp wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> I was curious if there are opinions regarding the congruence of forms
> (HTML <form>s) and links. It would seem to me that forms are an
> important part of hypertext navigation, and could be characterized as
> a user-input-parameterized link, at least with GET-based forms.

Yes, exactly.

> However, I was curious if others are in agreement on this perspective.

Yes, I guess everyone is :-)

> If a form is a type of link, why does HTML not define a "rel"
> attribute for forms?

Because it is argetted towards a human user which can cet the 'rel' from
the written text. See AtomPub's <collection> and <accept> elements for
a machine readable form.

> OpenSearch [1] also defines navigation to URIs
> that are parameterized by user-supplied data, but it does include
> "rel" attribute.

AFAIK, the rel attribute has a slightly different meaning in  
OpneSearch than it
does in links.

> From a navigational perspective, is there any
> fundamental difference between HTML form and OpenSearch links (other
> than that HTML obviously prescribes more of the presentation aspect)?

No. Only semantic differences.

> If forms can be viewed as link mechanisms, should this only be applied
> to GET-based forms, or can POST-driven user parametrized data also be
> considered a form of a navigable link?

It is equivalent in the sense that it takes you to a next state, but  
POST
requests are not idempotent and the client must be aware the it  
changes the
state of the server.

>
> The reason I ask, is I am trying to feel out if the approach in JSON
> schema, of allowing user-parametrized data submission [2] as an
> extension of a link definition is appropriate. With this approach,
> links can include additional information, extending them to take user
> provided data to form URIs, and specify the request method. IMO, this
> is an elegant way of minimizing constructs while still allowing for
> URIs to be parameterized with user input like forms, but I wasn't sure
> if others felt this would violate any principles of REST.

I'd need to look into that proposal, but can;t right now.

Jan


>
> [1] http://www.opensearch.org/Specifications/OpenSearch/1.1
> [2] http://tools.ietf.org/html/draft-zyp-json- 
> schema-01#section-6.1.1.3
>
> Thanks,
>
> - --
> Kris Zyp
> SitePen
> (503) 806-1841
> http://sitepen.com
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (MingW32)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
>
> iEYEARECAAYFAktgkW0ACgkQ9VpNnHc4zAwykACdHO/ORNeFFy5g07rzy90MzPSr
> zPMAoJmmg/UQJizuvys79ULqWfKTKmlY
> =4uDy
> -----END PGP SIGNATURE-----
>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

-----------------------------------
  Jan Algermissen, Consultant

  Mail: algermissen@...
  Blog: http://www.nordsc.com/blog/
  Work: http://www.nordsc.com/
-----------------------------------

Kris:

I view FORM elements as templated hypermedia links. in HTML the FORM
element is unique as it is the only link element that allows selection
of the HTTP method (GET, POST), too. I have built a few internal apps
that use a generic <link> element that contains nested <input>
elements. This sounds similar to what you are thinking about. FWIW, I
use the "rel" attribute on my invented link elements, too.

In the end this is about defining a media type. The elements you use
and the allowed child elements are up to you.

I will say that I've had mixed feelings about allowing a "method"
attribute. I've been toying with the idea of detailing any method
semantics against either the element itself or a "rel" attribute.

mca
http://amundsen.com/blog/




On Wed, Jan 27, 2010 at 14:18, Kris Zyp <kris@...> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> I was curious if there are opinions regarding the congruence of forms
> (HTML <form>s) and links. It would seem to me that forms are an
> important part of hypertext navigation, and could be characterized as
> a user-input-parameterized link, at least with GET-based forms.
> However, I was curious if others are in agreement on this perspective.
> If a form is a type of link, why does HTML not define a "rel"
> attribute for forms? OpenSearch [1] also defines navigation to URIs
> that are parameterized by user-supplied data, but it does include
> "rel" attribute. From a navigational perspective, is there any
> fundamental difference between HTML form and OpenSearch links (other
> than that HTML obviously prescribes more of the presentation aspect)?
> If forms can be viewed as link mechanisms, should this only be applied
> to GET-based forms, or can POST-driven user parametrized data also be
> considered a form of a navigable link?
>
> The reason I ask, is I am trying to feel out if the approach in JSON
> schema, of allowing user-parametrized data submission [2] as an
> extension of a link definition is appropriate. With this approach,
> links can include additional information, extending them to take user
> provided data to form URIs, and specify the request method. IMO, this
> is an elegant way of minimizing constructs while still allowing for
> URIs to be parameterized with user input like forms, but I wasn't sure
> if others felt this would violate any principles of REST.
>
> [1] http://www.opensearch.org/Specifications/OpenSearch/1.1
> [2] http://tools.ietf.org/html/draft-zyp-json-schema-01#section-6.1.1.3
>
> Thanks,
>
> - --
> Kris Zyp
> SitePen
> (503) 806-1841
> http://sitepen.com
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (MingW32)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
>
> iEYEARECAAYFAktgkW0ACgkQ9VpNnHc4zAwykACdHO/ORNeFFy5g07rzy90MzPSr
> zPMAoJmmg/UQJizuvys79ULqWfKTKmlY
> =4uDy
> -----END PGP SIGNATURE-----
>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

On Jan 27, 2010, at 8:58 PM, mike amundsen wrote:

> I will say that I've had mixed feelings about allowing a "method"
> attribute. I've been toying with the idea of detailing any method
> semantics against either the element itself or a "rel" attribute.

Yes, I think so, too. Since the client understands the semantics of
the transition it is taking anyway[1] there is usually no need to
specify the method in the hypertext.
Where it does make sense is in GET vs POST situations as OpenText
does because having a link to a result set (GET) and a link to
a newly created resource that is the result set (POST) has no
immediate impact on how you handle the result set.

Jan



[1] Except for crawlers, but these may only use GET anyway



-----------------------------------
  Jan Algermissen, Consultant

  Mail: algermissen@...
  Blog: http://www.nordsc.com/blog/
  Work: http://www.nordsc.com/
-----------------------------------

Kris:

<snip>
Where it does make sense is in GET vs POST situations as OpenText...
</snip>
Not sure I follow you there.

What I meant is (in the following examples), adding a "method"
attribute does not seem to help anything. In addition, adding the
method within the representation may bind the server needlessly.

<link rel="search" href="...">
�<input name="year" />
�<input name="month" />
</link>

<link rel="buy" href="..." />
�<input name="product" />
�<input name="quantity " />
</link>

<link rel="cancel" href="" />
�<input name="order-id" />
</link>

Finally, if i understand your example, my first sample markup might
support both GET and POST w/ POST creating a resource that can be
recalled later.

mca
http://amundsen.com/blog/




On Wed, Jan 27, 2010 at 15:26, Jan Algermissen <algermissen1971@...> wrote:
>
> On Jan 27, 2010, at 8:58 PM, mike amundsen wrote:
>
>> I will say that I've had mixed feelings about allowing a "method"
>> attribute. I've been toying with the idea of detailing any method
>> semantics against either the element itself or a "rel" attribute.
>
> Yes, I think so, too. Since the client understands the semantics of
> the transition it is taking anyway[1] there is usually no need to
> specify the method in the hypertext.
> Where it does make sense is in GET vs POST situations as OpenText
> does because having a link to a result set (GET) and a link to
> a newly created resource that is the result set (POST) has no
> immediate impact on how you handle the result set.
>
> Jan
>
>
>
> [1] Except for crawlers, but these may only use GET anyway
>
>
>
> -----------------------------------
> �Jan Algermissen, Consultant
>
> �Mail: algermissen@...
> �Blog: http://www.nordsc.com/blog/
> �Work: http://www.nordsc.com/
> -----------------------------------
>
>
>
>

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
 


On 1/27/2010 1:26 PM, Jan Algermissen wrote:
> 
>
>
> On Jan 27, 2010, at 8:58 PM, mike amundsen wrote:
>
> > I will say that I've had mixed feelings about allowing a "method"
> > attribute. I've been toying with the idea of detailing any method
> > semantics against either the element itself or a "rel" attribute.
>
> Yes, I think so, too. Since the client understands the semantics of
> the transition it is taking anyway[1] there is usually no need to
> specify the method in the hypertext.
>

To make sure I understand correctly, are you suggesting that ideally
link relations would specify (in the link registry) which method
should be used to navigate to the target URI? So perhaps a "create"
relation could be registered that specifies "POST" as the method to
use? Would this be problematic for custom relations that the client
may not be aware of the appropriate method for? Currently, the Atom
link registry does not specify any defined methods for any of the
existing relations that are registered. Even the "edit" relation
doesn't specify a method, it is still just GETable resource that one
can apply the uniform interface to.

- -- 
Kris Zyp
SitePen
(503) 806-1841
http://sitepen.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
 
iEYEARECAAYFAktgpagACgkQ9VpNnHc4zAxKswCgqEHhKdR8hgWrc8Yiy0ZrH3as
IeYAoKe9tvA7UZDSzGIIO41uQVBy3nYP
=MhL1
-----END PGP SIGNATURE-----

On Jan 27, 2010, at 9:45 PM, mike amundsen wrote:

> Kris:
>
> <snip>
> Where it does make sense is in GET vs POST situations as OpenText...

Doh - 'OpenSearch' of course

> </snip>
> Not sure I follow you there.
>
> What I meant is (in the following examples), adding a "method"
> attribute does not seem to help anything. In addition, adding the
> method within the representation may bind the server needlessly.
>
> <link rel="search" href="...">
>  <input name="year" />
>  <input name="month" />
> </link>
>
> <link rel="buy" href="..." />
>  <input name="product" />
>  <input name="quantity " />
> </link>
>
> <link rel="cancel" href="" />
>  <input name="order-id" />
> </link>
>
> Finally, if i understand your example, my first sample markup might
> support both GET and POST w/ POST creating a resource that can be
> recalled later.

Yes, that is what I meant.

Jan


>
> mca
> http://amundsen.com/blog/
>
>
>
>
> On Wed, Jan 27, 2010 at 15:26, Jan Algermissen <algermissen1971@... 
> > wrote:
>>
>> On Jan 27, 2010, at 8:58 PM, mike amundsen wrote:
>>
>>> I will say that I've had mixed feelings about allowing a "method"
>>> attribute. I've been toying with the idea of detailing any method
>>> semantics against either the element itself or a "rel" attribute.
>>
>> Yes, I think so, too. Since the client understands the semantics of
>> the transition it is taking anyway[1] there is usually no need to
>> specify the method in the hypertext.
>> Where it does make sense is in GET vs POST situations as OpenText
>> does because having a link to a result set (GET) and a link to
>> a newly created resource that is the result set (POST) has no
>> immediate impact on how you handle the result set.
>>
>> Jan
>>
>>
>>
>> [1] Except for crawlers, but these may only use GET anyway
>>
>>
>>
>> -----------------------------------
>>  Jan Algermissen, Consultant
>>
>>  Mail: algermissen@...
>>  Blog: http://www.nordsc.com/blog/
>>  Work: http://www.nordsc.com/
>> -----------------------------------
>>
>>
>>
>>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

-----------------------------------
  Jan Algermissen, Consultant

  Mail: algermissen@...
  Blog: http://www.nordsc.com/blog/
  Work: http://www.nordsc.com/
-----------------------------------

Kris:

I agree - linking methods only to "rel" values can be a problem.
However, defining this within the media-type is not. And it may be a
case of defining what clients can expect for each method rather than
restricting clients to using selected methods:

"rel='search'"
- GET will return 200 w/ the results
- POST will return 201 w/ Location header pointing to the results resource
- DELETE returns 200 OK if a valid search resource URI is passed
All other methods return 405

mca
http://amundsen.com/blog/




On Wed, Jan 27, 2010 at 15:44, Kris Zyp <kris@...> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
>
>
> On 1/27/2010 1:26 PM, Jan Algermissen wrote:
>>
>>
>>
>> On Jan 27, 2010, at 8:58 PM, mike amundsen wrote:
>>
>> > I will say that I've had mixed feelings about allowing a "method"
>> > attribute. I've been toying with the idea of detailing any method
>> > semantics against either the element itself or a "rel" attribute.
>>
>> Yes, I think so, too. Since the client understands the semantics of
>> the transition it is taking anyway[1] there is usually no need to
>> specify the method in the hypertext.
>>
>
> To make sure I understand correctly, are you suggesting that ideally
> link relations would specify (in the link registry) which method
> should be used to navigate to the target URI? So perhaps a "create"
> relation could be registered that specifies "POST" as the method to
> use? Would this be problematic for custom relations that the client
> may not be aware of the appropriate method for? Currently, the Atom
> link registry does not specify any defined methods for any of the
> existing relations that are registered. Even the "edit" relation
> doesn't specify a method, it is still just GETable resource that one
> can apply the uniform interface to.
>
> - --
> Kris Zyp
> SitePen
> (503) 806-1841
> http://sitepen.com
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (MingW32)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
>
> iEYEARECAAYFAktgpagACgkQ9VpNnHc4zAxKswCgqEHhKdR8hgWrc8Yiy0ZrH3as
> IeYAoKe9tvA7UZDSzGIIO41uQVBy3nYP
> =MhL1
> -----END PGP SIGNATURE-----
>
>

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
 


On 1/27/2010 1:56 PM, mike amundsen wrote:
>
>
> Kris:
>
> I agree - linking methods only to "rel" values can be a problem.
> However, defining this within the media-type is not. And it may be
> a case of defining what clients can expect for each method rather
> than restricting clients to using selected methods:
>
> "rel='search'" - GET will return 200 w/ the results - POST will
> return 201 w/ Location header pointing to the results resource -
> DELETE returns 200 OK if a valid search resource URI is passed All
> other methods return 405

I thought that ideally relations would be media type independent (have
the same semantics across media types). Furthermore, I would think it
would be desirable for media types to generally be protocol
independent. Specifying what methods and what status codes are
returned for relation in a media type definition seems like it would
violate both of these principles.
- -- 
Kris Zyp
SitePen
(503) 806-1841
http://sitepen.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
 
iEYEARECAAYFAktgqX4ACgkQ9VpNnHc4zAxzMgCgv45s5HeNZ5Dv62+5CbqTCCjN
PE8AnRgLnmxqpz9H/gGiin+V4lnBlfn6
=trGq
-----END PGP SIGNATURE-----

On Jan 27, 2010, at 9:44 PM, Kris Zyp wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
>
>
> On 1/27/2010 1:26 PM, Jan Algermissen wrote:
> >
> >
> >
> > On Jan 27, 2010, at 8:58 PM, mike amundsen wrote:
> >
> > > I will say that I've had mixed feelings about allowing a "method"
> > > attribute. I've been toying with the idea of detailing any method
> > > semantics against either the element itself or a "rel" attribute.
> >
> > Yes, I think so, too. Since the client understands the semantics of
> > the transition it is taking anyway[1] there is usually no need to
> > specify the method in the hypertext.
> >
>
> To make sure I understand correctly, are you suggesting that ideally
> link relations would specify (in the link registry) which method
> should be used to navigate to the target URI?

Yes. With GET being the default. The relation type describes the  
semantics of
the link target and these semantics include what kind of domain goals  
the client
can achive with requests to the target resource.

If you see <link rel="cart" href="./shopping-cart"/> and the type spec  
for 'cart'
tells you that a DELETE request on it empties the cart then you know  
that

DELETE ./shopping-cart achieves the domain goal of emptying the cart.

I started to describe that in http://www.nordsc.com/blog/?p=8

(last paragraph where it says: "express the operations that are  
currently stated
in the form of prose in hypermedia specifications in terms of the  
above predicate
conjunctions and HTTP operations")


> So perhaps a "create"
> relation could be registered that specifies "POST" as the method to
> use?

No, link relations denote resource semantics, not actions. The resource
semantics include what is achived by what requests on the resource.

If you say

<link rel="lock" href="/445/lock"/> these semantics might be that PUT
creates the lock and DELETE removes it.



> Would this be problematic for custom relations that the client
> may not be aware of the appropriate method for?

The cient needs to implement the semantics anyway. However, if the
HTTP connector implementation you use does not support all methods,
dump it and get a better one.

> Currently, the Atom
> link registry does not specify any defined methods for any of the
> existing relations that are registered.

If there is no such definition, no domain operations are involved. GET
makes sense by default.

> Even the "edit" relation
> doesn't specify a method, it is still just GETable resource that one
> can apply the uniform interface to.

No. The semantics of edit and edit-media are defined in the AtomPub  
specs and
there the effect of a PUT and DELETE to either of them is specified.

Jan


>
> - --
> Kris Zyp
> SitePen
> (503) 806-1841
> http://sitepen.com
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (MingW32)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
>
> iEYEARECAAYFAktgpagACgkQ9VpNnHc4zAxKswCgqEHhKdR8hgWrc8Yiy0ZrH3as
> IeYAoKe9tvA7UZDSzGIIO41uQVBy3nYP
> =MhL1
> -----END PGP SIGNATURE-----
>

-----------------------------------
  Jan Algermissen, Consultant

  Mail: algermissen@...
  Blog: http://www.nordsc.com/blog/
  Work: http://www.nordsc.com/
-----------------------------------

On Jan 27, 2010, at 9:44 PM, Kris Zyp wrote:

> So perhaps a "create"
> relation

Note that rels like 'edit' 'edit-media' or 'search' do not mean 'edit  
action here' but 'this is the edit-resource'

Jan




-----------------------------------
  Jan Algermissen, Consultant

  Mail: algermissen@...
  Blog: http://www.nordsc.com/blog/
  Work: http://www.nordsc.com/
-----------------------------------

> Note that rels like 'edit' 'edit-media' or 'search' do not mean 'edit action
Yep, verb-noun stuff here.

Wondering if there is any place for a verb in Uniform Interface apps?

mca
http://amundsen.com/blog/




On Wed, Jan 27, 2010 at 16:03, Jan Algermissen <algermissen1971@...> wrote:
>
> On Jan 27, 2010, at 9:44 PM, Kris Zyp wrote:
>
>> So perhaps a "create"
>> relation
>
> Note that rels like 'edit' 'edit-media' or 'search' do not mean 'edit action
> here' but 'this is the edit-resource'
>
> Jan
>
>
>
>
> -----------------------------------
> �Jan Algermissen, Consultant
>
> �Mail: algermissen@...
> �Blog: http://www.nordsc.com/blog/
> �Work: http://www.nordsc.com/
> -----------------------------------
>
>
>
>

On Jan 27, 2010, at 10:04 PM, mike amundsen wrote:

> Wondering if there is any place for a verb in Uniform Interface apps?

Yes, first word of request :-)

Sorry, could not resist.

Jan


>
> mca
> http://amundsen.com/blog/
>
>
>
>
> On Wed, Jan 27, 2010 at 16:03, Jan Algermissen <algermissen1971@... 
> > wrote:
>>
>> On Jan 27, 2010, at 9:44 PM, Kris Zyp wrote:
>>
>>> So perhaps a "create"
>>> relation
>>
>> Note that rels like 'edit' 'edit-media' or 'search' do not mean  
>> 'edit action
>> here' but 'this is the edit-resource'
>>
>> Jan
>>
>>
>>
>>
>> -----------------------------------
>>  Jan Algermissen, Consultant
>>
>>  Mail: algermissen@...
>>  Blog: http://www.nordsc.com/blog/
>>  Work: http://www.nordsc.com/
>> -----------------------------------
>>
>>
>>
>>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

-----------------------------------
  Jan Algermissen, Consultant

  Mail: algermissen@...
  Blog: http://www.nordsc.com/blog/
  Work: http://www.nordsc.com/
-----------------------------------

<snip>
>> Wondering if there is any place for a verb in Uniform Interface apps?
>
> Yes, first word of request :-)
</snip>

such a joker!

mca
http://amundsen.com/blog/




On Wed, Jan 27, 2010 at 16:07, Jan Algermissen <algermissen1971@...> wrote:
>
> On Jan 27, 2010, at 10:04 PM, mike amundsen wrote:
>
>> Wondering if there is any place for a verb in Uniform Interface apps?
>
> Yes, first word of request :-)
>
> Sorry, could not resist.
>
> Jan
>
>
>>
>> mca
>> http://amundsen.com/blog/
>>
>>
>>
>>
>> On Wed, Jan 27, 2010 at 16:03, Jan Algermissen <algermissen1971@...>
>> wrote:
>>>
>>> On Jan 27, 2010, at 9:44 PM, Kris Zyp wrote:
>>>
>>>> So perhaps a "create"
>>>> relation
>>>
>>> Note that rels like 'edit' 'edit-media' or 'search' do not mean 'edit
>>> action
>>> here' but 'this is the edit-resource'
>>>
>>> Jan
>>>
>>>
>>>
>>>
>>> -----------------------------------
>>> �Jan Algermissen, Consultant
>>>
>>> �Mail: algermissen@...
>>> �Blog: http://www.nordsc.com/blog/
>>> �Work: http://www.nordsc.com/
>>> -----------------------------------
>>>
>>>
>>>
>>>
>>
>>
>> ------------------------------------
>>
>> Yahoo! Groups Links
>>
>>
>>
>
> -----------------------------------
> �Jan Algermissen, Consultant
>
> �Mail: algermissen@...
> �Blog: http://www.nordsc.com/blog/
> �Work: http://www.nordsc.com/
> -----------------------------------
>
>
>
>

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
 


On 1/27/2010 2:01 PM, Jan Algermissen wrote:
>
>
>
> On Jan 27, 2010, at 9:44 PM, Kris Zyp wrote:
>
>
>
> On 1/27/2010 1:26 PM, Jan Algermissen wrote:
>
>
>
>> On Jan 27, 2010, at 8:58 PM, mike amundsen wrote:
>
>>> I will say that I've had mixed feelings about allowing a
>>> "method" attribute. I've been toying with the idea of detailing
>>> any method semantics against either the element itself or a
>>> "rel" attribute.
>
>> Yes, I think so, too. Since the client understands the semantics
>> of the transition it is taking anyway[1] there is usually no need
>> to specify the method in the hypertext.
>
>
> To make sure I understand correctly, are you suggesting that
> ideally link relations would specify (in the link registry) which
> method should be used to navigate to the target URI?
>
>> Yes. With GET being the default. The relation type describes the
>> semantics of the link target and these semantics include what
>> kind of domain goals the client can achive with requests to the
>> target resource.
>
>> If you see <link rel="cart" href="./shopping-cart"/> and the type
>> spec for 'cart' tells you that a DELETE request on it empties the
>> cart then you know that
>
>> DELETE ./shopping-cart achieves the domain goal of emptying the
>> cart.
>
>> I started to describe that in http://www.nordsc.com/blog/?p=8
>> <http://www.nordsc.com/blog/?p=8>
>
>> (last paragraph where it says: "express the operations that are
>> currently stated in the form of prose in hypermedia
>> specifications in terms of the above predicate conjunctions and
>> HTTP operations")
>
> So perhaps a "create" relation could be registered that specifies
> "POST" as the method to use?
>
>> No, link relations denote resource semantics, not actions. The
> resource
>> semantics include what is achived by what requests on the
>> resource.
>
I am confused, I thought you were saying that a link relation would
define what actions/verbs could be applied to the resource. Would it
be better if there was a "collection" relation that said that you
could GET and POST to it?

>> If you say
>
>> <link rel="lock" href="/445/lock"/> these semantics might be that
>> PUT creates the lock and DELETE removes it.
>
> Would this be problematic for custom relations that the client may
> not be aware of the appropriate method for?
>
>> The cient needs to implement the semantics anyway. However, if
>> the HTTP connector implementation you use does not support all
>> methods, dump it and get a better one.

I am not sure I understand. If a user agent gives user a selection
between different links/relations to follow, they should still be able
to follow the link without understanding the link relation definition,
shouldn't they?
>
> Currently, the Atom link registry does not specify any defined
> methods for any of the existing relations that are registered.
>
>> If there is no such definition, no domain operations are
>> involved. GET makes sense by default.
>
> Even the "edit" relation doesn't specify a method, it is still just
> GETable resource that one can apply the uniform interface to.
>
>> No. The semantics of edit and edit-media are defined in the
>> AtomPub specs and there the effect of a PUT and DELETE to either
>> of them is specified.

The effects described by AtomPub are just reiterating the already
prescribed effects defined by the uniform interface of the HTTP
protocol, aren't they? I don't see anything here [1] that suggests
that a target of the "edit" resource deviates from normal uniform
interface behavior.

http://bitworking.org/projects/atom/rfc5023.html#edit-via-PUT
- -- 
Kris Zyp
SitePen
(503) 806-1841
http://sitepen.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
 
iEYEARECAAYFAktgrIgACgkQ9VpNnHc4zAwFlgCfX8v+iUHBqv1cJUZpcosLUxut
rV0An3522rURI4Hbw4YpNko4PUeeMWPp
=Jg5B
-----END PGP SIGNATURE-----

On Jan 27, 2010, at 10:13 PM, Kris Zyp wrote:

>
>
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
>
>
> On 1/27/2010 2:01 PM, Jan Algermissen wrote:
> >
> >
> >
> > On Jan 27, 2010, at 9:44 PM, Kris Zyp wrote:
> >
> >
> >
> > On 1/27/2010 1:26 PM, Jan Algermissen wrote:
> >
> >
> >
> >> On Jan 27, 2010, at 8:58 PM, mike amundsen wrote:
> >
> >>> I will say that I've had mixed feelings about allowing a
> >>> "method" attribute. I've been toying with the idea of detailing
> >>> any method semantics against either the element itself or a
> >>> "rel" attribute.
> >
> >> Yes, I think so, too. Since the client understands the semantics
> >> of the transition it is taking anyway[1] there is usually no need
> >> to specify the method in the hypertext.
> >
> >
> > To make sure I understand correctly, are you suggesting that
> > ideally link relations would specify (in the link registry) which
> > method should be used to navigate to the target URI?

You can always *navigate* there with GET. If any other method achieves
some 'opration' then that must be specified as part of the relations
semantics. (which are the semantics of the target resource in the
given context)




> >
> >> Yes. With GET being the default. The relation type describes the
> >> semantics of the link target and these semantics include what
> >> kind of domain goals the client can achive with requests to the
> >> target resource.
> >
> >> If you see <link rel="cart" href="./shopping-cart"/> and the type
> >> spec for 'cart' tells you that a DELETE request on it empties the
> >> cart then you know that
> >
> >> DELETE ./shopping-cart achieves the domain goal of emptying the
> >> cart.
> >
> >> I started to describe that in http://www.nordsc.com/blog/?p=8
> >> <http://www.nordsc.com/blog/?p=8>
> >
> >> (last paragraph where it says: "express the operations that are
> >> currently stated in the form of prose in hypermedia
> >> specifications in terms of the above predicate conjunctions and
> >> HTTP operations")
> >
> > So perhaps a "create" relation could be registered that specifies
> > "POST" as the method to use?
> >
> >> No, link relations denote resource semantics, not actions. The
> > resource
> >> semantics include what is achived by what requests on the
> >> resource.
> >
> I am confused, I thought you were saying that a link relation would
> define what actions/verbs could be applied to the resource.

The desription of the relation defines the meaning of the target  
resource,
IWO: the end of the 'foo' link is a 'bar' resource. You achieve this and
that by PUTing to such 'bar' resources.

> Would it
> be better if there was a "collection" relation that said that you
> could GET and POST to it?

yes, exactly. In this sense, there is no difference between

<link rel="collection" href="...">

and

<collection href="...">

Which is why I called it "(named) hypermedia context" in the blog  
[sorry, but I
just had no better word for it]




>
> >> If you say
> >
> >> <link rel="lock" href="/445/lock"/> these semantics might be that
> >> PUT creates the lock and DELETE removes it.
> >
> > Would this be problematic for custom relations that the client may
> > not be aware of the appropriate method for?
> >
> >> The cient needs to implement the semantics anyway. However, if
> >> the HTTP connector implementation you use does not support all
> >> methods, dump it and get a better one.
>
> I am not sure I understand. If a user agent gives user a selection
> between different links/relations to follow, they should still be able
> to follow the link without understanding the link relation definition,
> shouldn't they?

With GET yes, for other methods, they'd better understand the effect the
request will have, eh?

> >
> > Currently, the Atom link registry does not specify any defined
> > methods for any of the existing relations that are registered.
> >
> >> If there is no such definition, no domain operations are
> >> involved. GET makes sense by default.
> >
> > Even the "edit" relation doesn't specify a method, it is still just
> > GETable resource that one can apply the uniform interface to.
> >
> >> No. The semantics of edit and edit-media are defined in the
> >> AtomPub specs and there the effect of a PUT and DELETE to either
> >> of them is specified.
>
> The effects described by AtomPub are just reiterating the already
> prescribed effects defined by the uniform interface of the HTTP
> protocol, aren't they?

No, they do (a bit) more. See media entry aspects.

> I don't see anything here [1] that suggests
> that a target of the "edit" resource deviates from normal uniform
> interface behavior.

I guess that is because the target resources do not have semantics  
outside
the HTTP domain. AtomPub sort of re-specifies parts of what is already  
inherent
in HTTP - and also overspecifies things that contradict HTTP. For  
example,
a server cannot be constrained (from HTTP POV) as to what to return for
a request on a certain resource. AtomPub does that and thus limits
server evolvability because it couples it to a client expectation
that is not part of HTTP.
(E.g. the spec says that requests to collection resource return Atom  
feed documents)

Jan

>
> http://bitworking.org/projects/atom/rfc5023.html#edit-via-PUT
> - --
> Kris Zyp
> SitePen
> (503) 806-1841
> http://sitepen.com
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (MingW32)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
>
> iEYEARECAAYFAktgrIgACgkQ9VpNnHc4zAwFlgCfX8v+iUHBqv1cJUZpcosLUxut
> rV0An3522rURI4Hbw4YpNko4PUeeMWPp
> =Jg5B
> -----END PGP SIGNATURE-----
>
>
>
> 

-----------------------------------
  Jan Algermissen, Consultant

  Mail: algermissen@...
  Blog: http://www.nordsc.com/blog/
  Work: http://www.nordsc.com/
-----------------------------------

Hi I've been looking for advice on how to design the representation
of a collection of references.

Supposing I have Seller resources, a list of which can be accessed at
/Sellers, and an individual Seller can be accessed at Sellers/{id}.
Also, I have Account resources. A list of Accounts linked to a Seller
can be accessed at /Sellers/{id}/Accounts. An individual account can be
found at /Sellers/{id1}/Accounts/{id2}

Just for now, let's assume I want an XML representation.

GET /Sellers/{id1}/Accounts/{id2} could return:

<Account id={id2} uri="/Sellers/{id1}/Accounts/{id2}"
attr1="abc" attr2="xyz" />

GET /Sellers/{id1}/Accounts could return:

<Accounts uri="/Sellers/{id1}/Accounts">
    <Account id={id2} uri="/Sellers/{id1}/Accounts/{id2}"
attr1="abc" attr2="xyz" />
    <Account id={id4} uri="/Sellers/{id1}/Accounts/{id4}"
attr1="efg" attr2="uvw" />
</Accounts>

And because I'm being pragmatic and know my clients are usually
interested in Accounts when dealing with a seller...

GET /Sellers/{id1} could return:

<Seller id={id1} uri="/Sellers/{id1}" attrA="mno"
attrB="pqr">
     <Accounts uri="/Sellers/{id1}/Accounts">
       <Account id={id2} uri="/Sellers/{id1}/Accounts/{id2}"
attr1="abc" attr2="xyz" />
       <Account id={id4} uri="/Sellers/{id1}/Accounts/{id4}"
attr1="efg" attr2="uvw" />
    </Accounts>
</Seller>

This works fine to my mind so long as the Account representation is not
too complex (or more importantly, large)... but what if it was? What if
an individual Account was so big it was inefficient to return all its
information when listing it (either as a standalone Accounts element
from /Sellers/{id1}/Accounts or a child element of Seller returned from
/Sellers/{id1})?

If I knew that 95% of the time my clients would have sufficient
information if each Account element in a list contained just an id, a
uri and a name attribute, I could decide to return only that basic data
when Accounts are listed.

But here is my question, finally, should that still be represented as:

    <Accounts><Account ... /><Account ... /></Accounts>

Or should I acknowledge it is not an account and change it to something
like:

    <AccountRefs><AccountRef ... /><AccountRef ... /></AccountRefs>

Which may have to be retrieved from /Sellers/{id1}/AccountRefs

The benefit of the first option is that the client would just deal with
Account resources. To create a new Account they could put it to
/Sellers/{id1}/Accounts, the URI for which is readily available. They
would have to realise though that the representation they PUT to that
URI is probably different from one they retrieve when they get a list of
Accounts (though it would be the same as the one they get when
retrieving an individual account).

The benefit of the second approach is that it is clear that the list
does not contain full blown Account details. Also, if I wanted to write
a schema describing the XML I could have different definitions for the
full "representation" of an Account resource and that of a
reference to an Account. However, this approach makes the creation of a
new Account more complex, as I in theory should PUT an Account somewhere
(but nothing in the list representation tells me where)... and I also
need to explicitly create the AccountRef (or have the server create it
as the Account is created).

I have swapped between which approach I prefer, though at the moment
I'm liking the first (i.e. sticking with Account). My reasoning...
It is just another representation of Account and I'm not aware of
anything that says each "view" of a resource must contain the
same information.

What do you think? Am I just missing the point altogether? Is this all
discussed in great depth elsewhere that I couldn't find (sorry if it
is)?

Thanks for your time.

Piers

piers_lawson wrote:
> Hi I've been looking for advice on how to design the representation
> of a collection of references.
> Supposing I have Seller resources, a list of which can be accessed
> at /Sellers, and an individual Seller can be accessed at Sellers/{id}.
> Also, I have Account resources. A list of Accounts linked to a Seller
> can be accessed at /Sellers/{id}/Accounts. An individual account can
> be found at /Sellers/{id1}/Accounts/{id2}
> Just for now, let's assume I want an XML representation. 
> 
> GET /Sellers/{id1}/Accounts/{id2} could return:
> <Account id={id2} uri="/Sellers/{id1}/Accounts/{id2}" attr1="abc"
> attr2="xyz" />
> 
> GET /Sellers/{id1}/Accounts could return:
> <Accounts uri="/Sellers/{id1}/Accounts">
> �� <Account id={id2} uri="/Sellers/{id1}/Accounts/{id2}"
> attr1="abc" attr2="xyz" />
> �� <Account id={id4} uri="/Sellers/{id1}/Accounts/{id4}"
> attr1="efg" attr2="uvw" />
> </Accounts>

Another issue to keep in mind is cache invalidation. When you duplicate information like Account attributes in the collection resource, you must invalidate the collection every time you invalidate each contained resource.

> And because I'm being pragmatic and know my clients are usually
> interested in Accounts when dealing with a seller... 
> GET /Sellers/{id1} could return:
> <Seller id={id1} uri="/Sellers/{id1}" attrA="mno" attrB="pqr">
> �� �<Accounts uri="/Sellers/{id1}/Accounts">
> �� ���<Account id={id2} uri="/Sellers/{id1}/Accounts/{id2}"
> attr1="abc" attr2="xyz" />
> �� ���<Account id={id4} uri="/Sellers/{id1}/Accounts/{id4}"
> attr1="efg" attr2="uvw" />
> �� </Accounts>
> </Seller>

Exponentially ditto here. HTTP is optimized for large-grain resources, but a large part of that depends on caching.

> This works fine to my mind so long as the Account representation
> is not too complex (or more importantly, large)... but what if it
> was? What if an individual Account was so big it was inefficient
> to return all its information when listing it (either as a
> standalone Accounts element from /Sellers/{id1}/Accounts

Then you should break it up into smaller resources, like /Accounts/{id2}/address/, and include links to those sub-resources in the response to /Accounts/{id2}/

> or a child element of Seller returned from /Sellers/{id1})?

Another good reason not to duplicate information from elements to their containers.

> ...
> Also, if I wanted to write a schema describing the XML
> I could have different definitions for the full
> "representation" of an Account resource and that of a
> reference to an Account. However, this approach makes
> the creation of a new Account more complex, as I in
> theory should PUT an Account somewhere (but nothing in
> the list representation tells me where)...

If instead of a new <AccountRef> class you just included a normal ol' URI, then that would be an exact reference to the full representation. You can also include a URI (or URI template) that tells you where to PUT a new Account.


Robert Brewer
fumanchu@...

"piers_lawson" wrote:
> 
> Hi I've been looking for advice on how to design the representation
> of a collection of references.
> 

Look no further than RFC 4287.

> 
> If I knew that 95% of the time my clients would have sufficient
> information if each Account element in a list contained just an id, a
> uri and a name attribute, I could decide to return only that basic
> data when Accounts are listed.
> 

This is a corollary to atom:summary vs. atom:content, you can have a
feed which contains atom:summary information, but atom:content has @src
which provides a link to the standalone Atom Entry's atom:content.  Atom
Feed documents are particularly well-suited to listing a collection of
names and IDs, where each contains or links to, more specific data.

> 
> What do you think? Am I just missing the point altogether? Is this all
> discussed in great depth elsewhere that I couldn't find (sorry if it
> is)?
> 

How you model your data is up to you; to me, it doesn't sound like
anything Atom can't handle.  If you don't use Atom, then you can at
least use standard link relations on your hyperlinks, or @src to refer
to documents within a collection, or other standard methods of linking
hypertext documents.

Try modeling your data as Atom first, though.  You may wind up being
pleased with the results you get from using standard media types and
link relations.

-Eric

On Jan 28, 2010, at 3:51 AM, Robert Brewer wrote:

> piers_lawson wrote:
>> Hi I've been looking for advice on how to design the representation
>> of a collection of references.
>> Supposing I have Seller resources, a list of which can be accessed
>> at /Sellers, and an individual Seller can be accessed at Sellers/ 
>> {id}.
>> Also, I have Account resources. A list of Accounts linked to a Seller
>> can be accessed at /Sellers/{id}/Accounts. An individual account can
>> be found at /Sellers/{id1}/Accounts/{id2}
>> Just for now, let's assume I want an XML representation.
>>
>> GET /Sellers/{id1}/Accounts/{id2} could return:
>> <Account id={id2} uri="/Sellers/{id1}/Accounts/{id2}" attr1="abc"
>> attr2="xyz" />
>>
>> GET /Sellers/{id1}/Accounts could return:
>> <Accounts uri="/Sellers/{id1}/Accounts">
>>    <Account id={id2} uri="/Sellers/{id1}/Accounts/{id2}"
>> attr1="abc" attr2="xyz" />
>>    <Account id={id4} uri="/Sellers/{id1}/Accounts/{id4}"
>> attr1="efg" attr2="uvw" />
>> </Accounts>
>
> Another issue to keep in mind is cache invalidation. When you  
> duplicate information like Account attributes in the collection  
> resource, you must invalidate the collection every time you  
> invalidate each contained resource.
>

Yes, good point (and often not discussed). Sometimes, you might hapen  
to know that the referenced resources are immutable (e.g. event  
history). Then the situation is different.

>> And because I'm being pragmatic and know my clients are usually
>> interested in Accounts when dealing with a seller...
>> GET /Sellers/{id1} could return:
>> <Seller id={id1} uri="/Sellers/{id1}" attrA="mno" attrB="pqr">
>>     <Accounts uri="/Sellers/{id1}/Accounts">
>>       <Account id={id2} uri="/Sellers/{id1}/Accounts/{id2}"
>> attr1="abc" attr2="xyz" />
>>       <Account id={id4} uri="/Sellers/{id1}/Accounts/{id4}"
>> attr1="efg" attr2="uvw" />
>>    </Accounts>
>> </Seller>
>
> Exponentially ditto here. HTTP is optimized for large-grain  
> resources, but a large part of that depends on caching.

Yes. And instead of fearing to-be-dereferenced references (<http://www.nordsc.com/blog/?p=152 
 > )  we should make use caching and conditional requests where it  
makes sense.


>
>> This works fine to my mind so long as the Account representation
>> is not too complex (or more importantly, large)... but what if it
>> was? What if an individual Account was so big it was inefficient
>> to return all its information when listing it (either as a
>> standalone Accounts element from /Sellers/{id1}/Accounts
>
> Then you should break it up into smaller resources, like /Accounts/ 
> {id2}/address/, and include links to those sub-resources in the  
> response to /Accounts/{id2}/
>
>> or a child element of Seller returned from /Sellers/{id1})?
>
> Another good reason not to duplicate information from elements to  
> their containers.

I'd generally put minimal information into the container to enable  
display. For example like Atom does with titles on links and with the  
summary element. If the content of both sticks to describing the  
nature of the target (which should not really change) you should not  
have any freshness problems.


>
>> ...
>> Also, if I wanted to write a schema describing the XML
>> I could have different definitions for the full
>> "representation" of an Account resource and that of a
>> reference to an Account. However, this approach makes
>> the creation of a new Account more complex, as I in
>> theory should PUT an Account somewhere (but nothing in
>> the list representation tells me where)...
>
> If instead of a new <AccountRef> class you just included a normal  
> ol' URI, then that would be an exact reference to the full  
> representation. You can also include a URI (or URI template) that  
> tells you where to PUT a new Account.

Yes.

Jan



>
>
> Robert Brewer
> fumanchu@...
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

-----------------------------------
  Jan Algermissen, Consultant

  Mail: algermissen@...
  Blog: http://www.nordsc.com/blog/
  Work: http://www.nordsc.com/
-----------------------------------

On Wed, Jan 27, 2010 at 11:07 PM, Eric J. Bowman <eric@...>wrote:

>
>
> "piers_lawson" wrote:
> >
> > Hi I've been looking for advice on how to design the representation
> > of a collection of references.
> >
>
> Look no further than RFC 4287.
>
>
I agree that Atom is a useful model for understanding how to represent
collections.  But, every time I try to use it in anger, I keep running into
some frustrations:

 * Atom is XML only -- I find JSON much easier for a general client base to
deal with.

* Even when I'm willing to deal with XML formats, it is pretty clumsy to
represent
  application specific content types -- you're pretty much talking about
custom
  XML namespaces, or about leveraging the XML "any" elements in the Atom
schema,
  which also basically negates the idea that a generic client is going to be
able to
  understand much about a particular message.

* There are a bunch of required attributes in the Atom "envelope" around the
  content that make perfect sense for the original use case (blog postings)
  but do not always make sense for particular application use cases.

* Yes, the concept of a standardized <link> element is quite useful for
expressing
  relationships between representations (and I like the idea that you can
define
  your own "rel" values).  But ...

  - You can have the same benefits in roll-your-own representations by
    emulating the <link> semantics in some appropriate local syntax.

  - Generic clients are not going to understand the semantics of custom
"rel"
    values anyway, so what is the value of packaging them in the standard
    Atom envelope?

Bottom line, I like the overall design paradigm that Atom defines, with well
defined semantics for the various CRUD operations that are almost univeral
across applications.  But, adhering to 4287 (versus my own custom collection
representation that shares the spirit of the <link> element for cross
referencing) doesn't seem to add huge amounts of value.  You're right, a
generic Atom client might understand the coarse grained message structure of
an "application/atom+xml;type=feed" media type, but I have a hard time
seeing why this matters if the client can't understand the actual
representation inside the <atom:content> element (or the equivalent custom
XML elements that the "any" construct in the schema allows) anyway.

For my own APIs (at least so far), I've followed these principles:

* Design a custom representation, with a custom media type,
  for each individual data object "class".

* Within the representation, include an extensible structure
  akin to the Atom <link> element, to define relationships
  between representations (as well as links to trigger state changers)
  but without the extra baggage of "required" Atom elements that
  are not relevant to the application specific use cases
  (let alone the limitation to use XML).

* Design an additional representation, with a "plural" name in
  the media type, for collections of the same type of data object.
  In XML, this would typically be something like as <customers>
  element around zero or more <customer> elements, with a
  media type like "application/vnd.com.example.myapp.Customers+xml"
  (or +json) for the collection, and
"application/vnc.com.example.myap.Customer+xml"
  for the representation of an individual customer.

I am aware that there are reasonable-sounding arguments for using "standard"
representation formats when they are available.  I'm just not sold on the
value, at least for the APIs I have been involved in so far.

Craig McClanahan

Craig McClanahan wrote:
>
> Eric J. Bowman wrote:
> 
> >
> >
> > "piers_lawson" wrote:
> > >
> > > Hi I've been looking for advice on how to design the
> > > representation of a collection of references.
> > >
> >
> > Look no further than RFC 4287.
> >
> >
> I agree that Atom is a useful model for understanding how to represent
> collections.  But, every time I try to use it in anger, I keep
> running into some frustrations:
> 
>  * Atom is XML only -- I find JSON much easier for a general client
> base to deal with.
> 

Atom is namespace-extensible and follows a schema.  Unless and until
JSON actually becomes a hypertext format, I'll stick to using hypertext
and standard link relations in REST applications.  I hold the opposite
view from yours on the XML-vs-JSON issue, entirely.  There is no
standard means to represent collections of data as JSON.  Whereas there
is application/atom+xml, which keeps that out-of-band knowledge wrapped
up in a common-knowledge standard media type, where it belongs -- not
in an API description.

>
> * Even when I'm willing to deal with XML formats, it is pretty clumsy
> to represent
>   application specific content types -- you're pretty much talking
> about custom
>   XML namespaces, or about leveraging the XML "any" elements in the
> Atom schema,
>   which also basically negates the idea that a generic client is
> going to be able to
>   understand much about a particular message.
> 

No, I'm not even suggesting that.  Atom provides a wrapper for XML of
any schema within atom:summary and atom:content elements.  All a
generic client, or intermediary, needs to know is right there in the
media type identifier of the response.  The user's agent will need to
know how to render the standard-or-nonstandard vocabulary presented in
the contents, but it needs no special knowledge of protocol-layer
messaging beyond that provided by Atom and Atom Protocol -- while an
intermediary only needs knowledge of the protocol-layer messaging but
no special knowledge of application-specific vocabulary.

The original question Piers was asking was also seeking advice on how
to create and update collection members.  If you are dealing with data
that can be modeled in Atom, you can use Atom Protocol to handle
creating and updating members in a standardized fashion, regardless of
the vocabulary used within atom:summary or atom:content elements.  I
don't know how any "generic" client is supposed to understand any
application-specific messaging that isn't described by the use of a
standard media type.

>
> * There are a bunch of required attributes in the Atom "envelope"
> around the content that make perfect sense for the original use case
> (blog postings) but do not always make sense for particular
> application use cases.
> 

You're right, Atom isn't always the answer.  But, it certainly helps to
start with modeling a system like Piers' in Atom, since it's a pretty
close fit out-of-the-box.  Patient records have a patient ID and a
patient Name and contact info.  In Atom, these would be under <author>
elements instead of <patient> elements.

The question is, whether it causes so much confusion for the system to
call patients "authors" that it outweighs the benefit of being able to
build the system using standard libraries for well-known media types
like Atom.  That same cost-benefit analysis needs to be applied to
every instance where a working model built with Atom is suboptimal to
the goals of the system.

So build a working model of the system, using Atom if it's even
remotely close to workable, because then you know exactly what
shortcomings are being addressed by the selection of some other
standard, or any custom, media types you proceed to choose or create.
Atom is hardly limited to "blogging", it applies to any sort of record
where it's important to know who said what to whom, when.  If the
actual data is a PDF or something, it can be handled as an attachment.

>
> * Yes, the concept of a standardized <link> element is quite useful
> for expressing
>   relationships between representations (and I like the idea that you
> can define
>   your own "rel" values).  
>

But, there's nothing standard about an application-specific link
relation.

>
> But ...
> 
>   - You can have the same benefits in roll-your-own representations by
>     emulating the <link> semantics in some appropriate local syntax.
> 

No, you can't.  Link semantics and syntax are clearly spelled out by
the relevant standards which describe them (as defined by media type
identifier used), and there is expected to be a new registry for
standardized link relations to be used in HTTP Link header syntax.
REST quite clearly calls for the use of standard or standardizable
methods and media types, the combination of which encapsulates all out-
of-band knowledge of an API within common knowledge.

Nonstandard vocabularies are allowed inside of standard media types,
but embedding standard link relations inside nonstandard vocabularies
defeats the entire purpose.

>
>   - Generic clients are not going to understand the semantics of
> custom "rel"
>     values anyway, so what is the value of packaging them in the
> standard Atom envelope?
> 

Who said anything about custom rel values?  The OP is clearly
describing a problem that's easily solved by the standard link
relations defined within Atom.  Granted, those link relations can be
used in other media types, but if those other media types aren't
standard then the system isn't built in the REST style.

If a patient can have an atom:id, then so can a Doctor.  It follows,
then, that a medical recordkeeping system would need a vocabulary of
link relations specific to that type of system, for linking Doctors and
patients -- a patient record of a Dr. visit might have a link to the
atom:id of the referring Dr. which would need a different link relation
that that of the attending Dr.

But, Atom allows for such extension, and such a vocabulary, if generic
enough, could see adoption elsewhere.  After which, a standard emerges
establishing consensus for a Medical Records extension vocabulary for
Atom.  Now that I have said something about custom rel values, why
would a generic client, or intermediary, need to understand application
specifics like referring vs. attending physician?  All I care about is
that the (human|machine) user's agent can interpret this information.

A hypertext application can easily be built based on those link
relations, which allows for the correct display and manipulation of
system resources.  The user's agent is thus taught all it needs to
know, and the link relations don't need to be standardized for it to
work.  REST requires the standardization of these link relations, for
purposes beyond just making the application work -- to make it work for
others in an interoperable way over time, requires that the out-of-band
knowledge encapsulated in these link relations is (or becomes) common
knowledge.

>
> Bottom line, I like the overall design paradigm that Atom defines,
> with well defined semantics for the various CRUD operations that are
> almost univeral across applications.  But, adhering to 4287 (versus
> my own custom collection representation that shares the spirit of the
> <link> element for cross referencing) doesn't seem to add huge
> amounts of value.  You're right, a generic Atom client might
> understand the coarse grained message structure of an
> "application/atom+xml;type=feed" media type, but I have a hard time
> seeing why this matters if the client can't understand the actual
> representation inside the <atom:content> element (or the equivalent
> custom XML elements that the "any" construct in the schema allows)
> anyway.
> 

I don't see why a client can't be instructed, via an XSLT
transformation, how to present any custom XML vocabulary presented
within atom:summary/atom:content elements as HTML documents.  At the
wire level, protocol interaction simply doesn't require knowledge of
any custom vocabulary within representations of standard media types.

>
> For my own APIs (at least so far), I've followed these principles:
> 
> * Design a custom representation, with a custom media type,
>   for each individual data object "class".
> 

OK, you're not the first person I've heard promoting this design meme,
but you will be the first person I ask why...  Where do you find any
support for this notion within REST or anything else Dr. Fielding has
written about REST?  The REST style calls for obeying the standards
used.  I'm assuming you're using the HTTP protocol, in which case RFC
2616 applies, along with its SHOULD NOT admonishment against using
unregistered media types.

I've written extensively in recent threads about all the things Roy and
REST do say about media type proliferation, so aside from going against
RFC 2616 this design pattern does not have any conceivable support from
within REST, which calls for the re-use of existing standard media
types.  That there are people out there who are minting media types for
each representation type on their system, boggles my mind.

This goes against all custom and practice in Web Development, where the
closest you'll come to an example was Atom Protocol's adding the type
parameter to the application/atom+xml media type identifier.
Additionally, you suggest that Atom is only useful for blogging,
instead of its actual intent to be an extensible, all-purpose re-usable
wrapper, the very notion of which seems alien to the mint-new-media-
types-for-everything approach.  You also suggest a 1:1 relationship
between media types and media type identifiers, which doesn't exist,
and isn't required unless media type identifiers are being mis-used as
"contracts".

REST development starts with modeling resources; once modeled, those
resources are assigned an appropriate media type.  Only once all
existing media types are deemed inappropriate, is it OK to forge ahead
with minting a new one.  This is designing within the constraints of
REST.  The unbounded-creativity approach of treating each of your
representations as a unique snowflake without considering the
possibility that a standard media type may be a perfect fit, is in
direct conflict with the REST style.

>
> * Within the representation, include an extensible structure
>   akin to the Atom <link> element, to define relationships
>   between representations (as well as links to trigger state changers)
>   but without the extra baggage of "required" Atom elements that
>   are not relevant to the application specific use cases
>   (let alone the limitation to use XML).
> 

I certainly don't see how any generic client is going to understand
what you suggest.  To quote from REST:

"
The trade-off, though, is that a uniform interface degrades efficiency,
since information is transferred in a standardized form rather than one
which is specific to an application's needs.
"

If you're unwilling to make this trade-off, then perhaps REST isn't the
right architecture for your system.  What you consider "baggage" is
considered by plenty of others as the essential bare-minimum information
pertinent to who said what to whom, when.  While some of this data may
be irrelevant to your specific application, the use of a standard media
type allows for serendipitous re-use.  Atom does force you to provide
the who said what to whom, when-metadata, even if you aren't using it in
your interface, because it's critical to allowing others to use your
API for purposes you never conceived.

I also have no idea what you mean when you say Atom is limited to XML.

>
> * Design an additional representation, with a "plural" name in
>   the media type, for collections of the same type of data object.
>   In XML, this would typically be something like as <customers>
>   element around zero or more <customer> elements, with a
>   media type like "application/vnd.com.example.myapp.Customers+xml"
>   (or +json) for the collection, and
> "application/vnc.com.example.myap.Customer+xml"
>   for the representation of an individual customer.
> 

You've now minted two media types that are specific to your application
and do not represent common knowledge.  Your API is thus driven by out-
of-band knowledge presented in its documentation, rather than a shared
understanding of common media types and link relations.  I don't
understand how a generic client, or intermediary, can understand
anything about your payload other than what's implied by application/xml
because RFC 3023 allows for the extension of that media type identifier.

However, no such corollary exists in RFC 4627, so your +json media type
identifiers will be treated by generic clients, or intermediaries, as
an invalid declaration and may forward or interpret the message as
text/plain or application/octet-stream, or remove the Content-Type
header entirely.

I also have no idea what you mean by "typically be something like..."
If you're just using Atom, and not Atom Protocol, then <feed> wraps
<entry> unless <entry> is the root element, and either way they have
the same media type.  In Atom Protocol, it is optional to use a type
parameter, both type=feed and type=entry are defined.  I don't bother
with type=entry, but I do use type=feed.  These are subtypes, and this
is the proper way to handle collections/members rather than assigning
two separate media type identifiers -- how is any generic client, or
intermediary, to understand that *.Customer+xml and *.Customers+xml are
in any way related to one another?  These are separate, opaque
identifers rather than an identical media type with separate, opaque
subtypes.

>
> I am aware that there are reasonable-sounding arguments for using
> "standard" representation formats when they are available.  I'm just
> not sold on the value, at least for the APIs I have been involved in
> so far.
> 

REST doesn't call this an optional constraint -- self-descriptive
messaging is critical to the entire style.  If you're relying on out-
of-band information based on the syntax of custom media type identifiers
then specific knowledge of your API is required for any intermediary or
client to make heads or tails of its payload.  If you're using standard
media types, then generic clients may be instructed how to deal with
any uncommon knowledge about your API, using hypertext representations.

Nobody has managed to sell me on any pragmatic value to disregarding
the self-descriptive messaging constraint.  There is value in allowing
intermediaries and generic clients to determine the nature of a payload
by keying on standard media type identifiers.  It comes with a tradeoff
of efficiency that I'm willing to make in order to gain the positive
benefits of scaling and serendipitous re-use, which is why I use REST.
If there were some hidden value in disregarding the self-descriptive
messaging constraint that disproves REST's utility, then I wouldn't pay
REST any mind, but so far no such inherent contradiction has been
exposed.  IOW, my response has nothing to do with dogma, and everything
to do with why the Web succeeded in the first place.

-Eric

--- In rest-discuss@yahoogroups.com, mike amundsen <mamund@...> wrote:
>
> > Note that rels like 'edit' 'edit-media' or 'search' do not mean 'edit action
> Yep, verb-noun stuff here.
> 
> Wondering if there is any place for a verb in Uniform Interface apps?
> 
> mca
> http://amundsen.com/blog/
> 

Absolutely! Client side events are often named after verbs (e.g. change, blur, focus, load). If your hypermedia format is event driven, that's where your verbs will be.

Oh well, ya... the HTTP verbs too (as Jan said). 

A role of hypermedia can be the filtering and conversion of the client side events/verbs to server requests/verbs.

Andrew

Hi All,

I was wondering how you would implement a RESTful CAPTCHA solution,
especially in the context of the strict interpretation of 'statelessness'
many on this list use. I would assume the 'naive' solution would be to send
a hash of the answer to the user and then use both the hash (which the user
returns to the server) and the answer on the server side to see if they
match. But that exposes the server to replay attacks. The approach I would
take (which violates the 'strict interpretation' of statelessness) would be
to create a new resource for the captcha on the server and compare the
incoming answer with that, destroying the resource when done.

I am unsure what approach would satisfy both requirements. My intention for
starting this discussion is not to inflame, but to better understand the
'strict' statelessness POV.

Thanks,
Alexandros.

How about this:

When a person requests the representation to fill out (the one w/ the
captcha rendering)
- generate a captcha image and create a new resource for it
(/captchas/a1s2d3f3g4)
- in the response representation, include an embed link (<img />) to the
generated captcha resource _and_ a hidden input that contains the same URI

When the user POSTs the representation back, it can include a pointer to the
captcha resource (from the hidden input) as well as the user's input text.
You can use that pointer to validate the input text passed by the user.

The images could be generated ahead of time or on deamand. The URIs could be
completely random or a hash of the actual captcha text to short-cut the
validation process. The captcha URIs can be marked as single-use and even
limited time-valid to cut down on flooding, etc.

mca
http://amundsen.com/blog/



On Sat, Jan 30, 2010 at 10:07, Alexandros Marinos <al3xgr@...> wrote:

>
>
> Hi All,
>
> I was wondering how you would implement a RESTful CAPTCHA solution,
> especially in the context of the strict interpretation of 'statelessness'
> many on this list use. I would assume the 'naive' solution would be to send
> a hash of the answer to the user and then use both the hash (which the user
> returns to the server) and the answer on the server side to see if they
> match. But that exposes the server to replay attacks. The approach I would
> take (which violates the 'strict interpretation' of statelessness) would be
> to create a new resource for the captcha on the server and compare the
> incoming answer with that, destroying the resource when done.
>
> I am unsure what approach would satisfy both requirements. My intention for
> starting this discussion is not to inflame, but to better understand the
> 'strict' statelessness POV.
>
> Thanks,
> Alexandros.
>
>
> 

mike amundsen wrote:
> 
> 
> How about this:
> 
> When a person requests the representation to fill out (the one w/ the 
> captcha rendering)
> - generate a captcha image and create a new resource for it 
> (/captchas/a1s2d3f3g4)
> - in the response representation, include an embed link (<img />) to the 
> generated captcha resource _and_ a hidden input that contains the same URI

That would mean that every access to the form would have to be via POST (because generating the image resource is a side-effect and therefore not allowed for GET) so you can't simply link to the form.

Regards,
  Simon

I have several implementations that write logs, audit trails, and
create other data (that may or may not be exposed as a resource) for
later use on every GET. The important thing is that the same GET can
be repeated many times w/o any harm and will return (from the client's
POV) the same expected results.

This includes records used to track single-use URI tokens and could
also be used to generate and track Captcha information.

I don't see a problem w/ HTTP specs or REST style in this.

mca
http://amundsen.com/blog/




On Sat, Jan 30, 2010 at 20:08, Simon Reinhardt <simon.reinhardt@...> wrote:
> mike amundsen wrote:
>>
>>
>> How about this:
>>
>> When a person requests the representation to fill out (the one w/ the
>> captcha rendering)
>> - generate a captcha image and create a new resource for it
>> (/captchas/a1s2d3f3g4)
>> - in the response representation, include an embed link (<img />) to the
>> generated captcha resource _and_ a hidden input that contains the same URI
>
> That would mean that every access to the form would have to be via POST
> (because generating the image resource is a side-effect and therefore not
> allowed for GET) so you can't simply link to the form.
>
> Regards,
> �Simon
>

Hi,

I'm planning to develop a webservice, and I like to try the RESTful 
architecture.

The service is about downloading some data from the server to a device 
attached on the local computer. The client need to retrieve the command 
from the server and then send the response of the device to the server 
to check its validity. Then the server says if it is ok or not.

  Device      client     Server
                    ---->      Get command
        <-----      <-----

        ---->       ---->      Response from device
   		   <-----     Response from server indicating
                               if it is ok or not the execution

It would be like: client calls authenticate of device. then the server 
sends the command to be sent to the device for authentication. The 
client send this command to the device and the response is sent back to 
the server. The server then replies.

I have thought on:
     /device/{id}   as resource
     /device/{id}/authenticate
          GET will retrieve the command and blank state
              <command> value </command>
              <state> not defined </command>
          PUT will send the response and get the real state
              ---> <response> value </response>
              <--- <state> not defined </command>

I don't know if this is REST. Is it better to create another resource as:
     /device/{id}/authenticate/command  (only GET available)
     /device/{id}/authenticate/response (only PUT available)
     /device/{id}/authenticate          (only GET avaliable for status)

Any help is welcome.
TA

Does the media type define when the client reaches a staedy-state or is this a client configuration issue?

There is definitely overlap: HTML surely at least implies that a steady state is reached when all inline media has been retrieved but I can tell my client to not download, for example, images and thus reach a steady state earlier.

But would it also be conceptually ok to configure a client to do more until a steady state is reached? That is, perform some other requests using partiluar domain semantics of an accessed service?

For example, think of a client configuration that would cause the client to allways execute several searches when the home page of an online store is reached that provides OpenSearch forms?

jan



-----------------------------------
 Jan Algermissen, Consultant

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

George,

On Jan 30, 2010, at 1:38 PM, George wrote:

> Hi,
> 
> I'm planning to develop a webservice, and I like to try the RESTful 
> architecture.
> 
> The service is about downloading some data from the server to a device 
> attached on the local computer. The client need to retrieve the command 
> from the server and then send the response of the device to the server 
> to check its validity. Then the server says if it is ok or not.

I think I do not understand what you are up to. Why does the client fetch the command for the device from the server?



> 
>  Device      client     Server
>                    ---->      Get command
>        <-----      <-----
> 
>        ---->       ---->      Response from device
>   		   <-----     Response from server indicating
>                               if it is ok or not the execution
> 
> It would be like: client calls authenticate of device. then the server 
> sends the command to be sent to the device for authentication.

HTTP authentication is orthogonal. Use one of the HTTP standard authentication solutions.


> The 
> client send this command to the device and the response is sent back to 
> the server. The server then replies.
> 
> I have thought on:
>     /device/{id}   as resource
>     /device/{id}/authenticate
>          GET will retrieve the command and blank state
>              <command> value </command>
>              <state> not defined </command>
>          PUT will send the response and get the real state
>              ---> <response> value </response>
>              <--- <state> not defined </command>
> 
> I don't know if this is REST. Is it better to create another resource as:
>     /device/{id}/authenticate/command  (only GET available)
>     /device/{id}/authenticate/response (only PUT available)
>     /device/{id}/authenticate          (only GET avaliable for status)
> 
> Any help is welcome.

Can you explain your requirements? I am having trouble understanding what you are trying to do.

Jan



> TA
> 
> 
> 
> 
> 
> 
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Hi,

Let's try to explain it a little further.


On 01/02/2010 9:02, Jan Algermissen wrote:
> George,
>
> On Jan 30, 2010, at 1:38 PM, George wrote:
>
>> Hi,
>>
>> I'm planning to develop a webservice, and I like to try the RESTful
>> architecture.
>>
>> The service is about downloading some data from the server to a device
>> attached on the local computer. The client need to retrieve the command
>> from the server and then send the response of the device to the server
>> to check its validity. Then the server says if it is ok or not.
>
> I think I do not understand what you are up to. Why does the client fetch the command for the device from the server?

The system is foreseen to control a hardware device. The issue is that 
the device only accepts a subset of commands based on some cryptographic 
features.

I don't want the command set and the cryptographic keys to be on the 
client, as this way I have to replicate the keys on every client and the 
security can be comprised.

Each command is encrypted with different keys depending on the device it 
is directed to. So the issue is first is that the server needs to know 
the device as to open the session with the correct set of keys. After 
that, the client get the command (encripted and maced with server keys), 
this command is sent to the device who will response. The response has 
some crypto stuff that need to be check on the server. Then the client 
get an ACK or NACK depending on the correct answer from the device 
(whether the command is well executed or not, or whether the device owns 
the correct set of keys and it not a fake device).

>
>
>
>>
>>   Device      client     Server
>>                     ---->       Get command
>>         <-----<-----
>>
>>         ---->        ---->       Response from device
>>    		<-----     Response from server indicating
>>                                if it is ok or not the execution
>>
>> It would be like: client calls authenticate of device. then the server
>> sends the command to be sent to the device for authentication.
>
> HTTP authentication is orthogonal. Use one of the HTTP standard authentication solutions.

Authentication is done based on the crypto protocol that I explained above.

>
>
>> The
>> client send this command to the device and the response is sent back to
>> the server. The server then replies.
>>
>> I have thought on:
>>      /device/{id}   as resource
>>      /device/{id}/authenticate
>>           GET will retrieve the command and blank state
>>               <command>  value</command>
>>               <state>  not defined</command>
>>           PUT will send the response and get the real state
>>               --->  <response>  value</response>
>>               <---<state>  not defined</command>
>>
>> I don't know if this is REST. Is it better to create another resource as:
>>      /device/{id}/authenticate/command  (only GET available)
>>      /device/{id}/authenticate/response (only PUT available)
>>      /device/{id}/authenticate          (only GET avaliable for status)
>>
>> Any help is welcome.
>
> Can you explain your requirements? I am having trouble understanding what you are trying to do.

The issue is that I need to get a command and then check the answer from 
that command. This will be done in 2 steps, and I don't know how to map 
that into resources.

Thanks... hope now is clearer.

CU
Jorge

> Jan
>
>
>
>> TA
>>
>>
>>
>>
>>
>>
>>
>>
>> ------------------------------------
>>
>> Yahoo! Groups Links
>>
>>
>>
>
> -----------------------------------
>   Jan Algermissen, Consultant
>
>   Mail: algermissen@...
>   Blog: http://www.nordsc.com/blog/
>   Work: http://www.nordsc.com/
> -----------------------------------
>
>
>

Hey all, 

The first week of This Week in REST is over (I think it was a successful test run) and you can find the collected links for last week (Jan 25 2010 � Jan 31 2010) on:
* the REST wiki - http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Jan_25_2010
* the blog I've started for feed-based distribution - http://thisweekinrest.wordpress.com/2010/02/01/this-week-in-rest-volume-1-jan-25-2010-jan-31-2010/

For contributing links this week (please do!) visit http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Feb_1_2010

Cheers,
Ivan

Jan Algermissen wrote:
>
> Does the media type define when the client reaches a staedy-state or
> is this a client configuration issue?
> 

Media type.

>
> There is definitely overlap: HTML surely at least implies that a
> steady state is reached when all inline media has been retrieved but
> I can tell my client to not download, for example, images and thus
> reach a steady state earlier.
> 

Yes, but that behavior is defined by the media type -- HTML defines
@alt for inline images and the <noscript> element to provide graceful
fallback based on client configurations of !image and/or !script which
the media type explicitly allows for.

>
> But would it also be conceptually ok to configure a client to do more
> until a steady state is reached? That is, perform some other requests
> using partiluar domain semantics of an accessed service?
>

Sure.  You're just applying the layered-system constraint on the client
side.  Thus, your client state becomes separated from application state.
Application state is entirely derived from the retrieved representation,
while actual client state is opaque to the server component which sent
the representation, because it "cannot 'see' beyond the immediate layer
with which [it interacts]," to paraphrase REST.

>
> For example, think of a client configuration that would cause the
> client to allways execute several searches when the home page of an
> online store is reached that provides OpenSearch forms?
> 

I think that's out of scope to REST, which is only concerned with the
interactions between connectors in a system.  What the user's agent
actually does with the retrieved representations is opaque behind the
uniform interface.  The media type tells the client all it really needs
to know about rendering the document to obtain application state,
doesn't it?

For example, a user may employ an accessibility agent which performs
specific actions based on content.  Or a Web accelerator which follows
and pre-caches DNS responses and retrieved representations that a user
hasn't yet requested, or what you suggested.  I just don't think REST
cares about any of that. I would call these examples "enhanced client
state", but I don't see how any of that affects "application state" as
envisioned by the server through its media-type declaration.

-Eric

Jan Algermissen wrote:
> On Jan 24, 2010, at 4:46 PM, Mike Kelly wrote:
>
>   
>> Jan Algermissen wrote:
>>     
>>> On Jan 24, 2010, at 2:07 PM, Mike Kelly wrote:
>>>
>>>
>>>       
>>>> the only way for the client to understand the 'meaning' of its   
>>>> current state is in the context of the application flow (i.e.  
>>>> series  of link relations) which led up to it.
>>>>
>>>>         
>>> Correct me, but this is exactly what REST prevents. A client can  
>>> use  the URI of any steady-state and just proceed through the  
>>> application  from that point on without the need for any knowledge  
>>> about prior  interactions. If it can't, the representation is just  
>>> badly designed.
>>>
>>>       
>> Are we drawing a distinction here between steady-state and entry- 
>> point?
>>     
>
> Hmm, IMHO each steady state is a potential entry point.
>   

I can't agree with that - and don't think the quote you dug up is 
referring to this specific issue.

For a machine client, RESTing at a given steady state and establishing 
its 'meaning' is a much more delicate affair than for a human client. We 
have fuzzy methods of inference and contextualization with humans that 
we just don't have the luxury of with machines.

I think we need to agree on the definition of 'meaning' in this 
context.. because, to me, it includes more than just the current set of 
available link relations, and since we're not supposed to type resources 
- the only approach I can see working is predefined application flows 
(which may or may not contain several 'steady states') driven by link 
relations.

- Mike

On Feb 1, 2010, at 1:38 PM, Mike Kelly wrote:

> I think we need to agree on the definition of 'meaning' in this 
> context.. because, to me, it includes more than just the current set of 
> available link relations, and since we're not supposed to type resources 
> - the only approach I can see working is predefined application flows

Predefined application flows violate the hypermedia constraint and couple the server in a way that REST deliberately aims to avoid. As you know from my questions on this list around this issue I have been banging my head against that wall, but the more it hurt, the clearer the picture became (for me at least) :-)

It is really as simple as this:

o The client needs an understanding of the set of media types that the service uses, IOW, the set of types the client has to be able to deal with. (this is what I think makes up a service type for discovery and 'governance' purposes)

o For any request the client sends it must expect any HTTP response code and a representation of any of the set of media types. It is completely up to the client to deal with whatever it receives. 4xx is not 'broken contract' but an *essential* part of the contract.

o The server has the obligation to not lie about the links it sends, e.g. using <img src=""/> to point to an Atom feed can be considered a broken server

o The server must keep resource sematics stable (and steady state (==bookmarkable) resources should be presistent)

Bottom line: it is really about putting *all* change handling into the clients (and to actively expect change) to allow independent server evolution and avoid ned for communication between server and client owners.

The funny thing for me was that, once actively accepting these consequences, it turns out there is really not so much that can change about a server given the above obligations. REST externalises everything about an API that *can* be kept stable and lets the client deal with the remaining instabilities.

Jan


> (which may or may not contain several 'steady states') driven by link 
> relations.

-----------------------------------
 Jan Algermissen, Consultant

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Jan Algermissen wrote:
> On Feb 1, 2010, at 1:38 PM, Mike Kelly wrote:
>
>   
>> I think we need to agree on the definition of 'meaning' in this 
>> context.. because, to me, it includes more than just the current set of 
>> available link relations, and since we're not supposed to type resources 
>> - the only approach I can see working is predefined application flows
>>     
>
> Predefined application flows violate the hypermedia constraint and couple the server in a way that REST deliberately aims to avoid. 
>   

Predefined application flows like AtomPub violate the hypermedia constraint?

> It is really as simple as this:
>
> o The client needs an understanding of the set of media types that the service uses, IOW, the set of types the client has to be able to deal with. (this is what I think makes up a service type for discovery and 'governance' purposes)
>   

I would choose to say 'set of representations' over 'set of media 
types'. Those representations will define types of link relations, which 
in turn define the application flow(s). Over time - other links/flows 
can be added, resources moved, media-types added etc. This is what I 
have understood as evolveability aspect of REST wrt the hypertext 
constraint.

>
> The funny thing for me was that, once actively accepting these consequences, it turns out there is really not so much that can change about a server given the above obligations. 

Ok - are you saying this is a Good Thing?

- Mike

Subscribed!

thanks.

mca
http://amundsen.com/blog/




On Mon, Feb 1, 2010 at 05:29, izuzak <izuzak@...> wrote:
> Hey all,
>
> The first week of This Week in REST is over (I think it was a successful test run) and you can find the collected links for last week (Jan 25 2010 � Jan 31 2010) on:
> * the REST wiki - http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Jan_25_2010
> * the blog I've started for feed-based distribution - http://thisweekinrest.wordpress.com/2010/02/01/this-week-in-rest-volume-1-jan-25-2010-jan-31-2010/
>
> For contributing links this week (please do!) visit http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Feb_1_2010
>
> Cheers,
> Ivan
>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

Eric,

On Feb 1, 2010, at 11:50 AM, Eric J. Bowman wrote:

> Jan Algermissen wrote:
>> 
>> Does the media type define when the client reaches a staedy-state or
>> is this a client configuration issue?
>> 
> 
> Media type.
> 
>> 
>> There is definitely overlap: HTML surely at least implies that a
>> steady state is reached when all inline media has been retrieved but
>> I can tell my client to not download, for example, images and thus
>> reach a steady state earlier.
>> 
> 
> Yes, but that behavior is defined by the media type -- HTML defines
> @alt for inline images and the <noscript> element to provide graceful
> fallback based on client configurations of !image and/or !script which
> the media type explicitly allows for.
> 
>> 
>> But would it also be conceptually ok to configure a client to do more
>> until a steady state is reached? That is, perform some other requests
>> using partiluar domain semantics of an accessed service?
>> 
> 
> Sure.  You're just applying the layered-system constraint on the client
> side.  Thus, your client state becomes separated from application state.
> Application state is entirely derived from the retrieved representation,
> while actual client state is opaque to the server component which sent
> the representation, because it "cannot 'see' beyond the immediate layer
> with which [it interacts]," to paraphrase REST.
> 
>> 
>> For example, think of a client configuration that would cause the
>> client to allways execute several searches when the home page of an
>> online store is reached that provides OpenSearch forms?
>> 
> 
> I think that's out of scope to REST, which is only concerned with the
> interactions between connectors in a system.  What the user's agent
> actually does with the retrieved representations is opaque behind the
> uniform interface.  The media type tells the client all it really needs
> to know about rendering the document to obtain application state,
> doesn't it?
> 
> For example, a user may employ an accessibility agent which performs
> specific actions based on content.  Or a Web accelerator which follows
> and pre-caches DNS responses and retrieved representations that a user
> hasn't yet requested, or what you suggested.  I just don't think REST
> cares about any of that. I would call these examples "enhanced client
> state", but I don't see how any of that affects "application state" as
> envisioned by the server through its media-type declaration.
> 

Yepp, that is pretty much how I see it also.

Jan




> -Eric
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

On Feb 1, 2010, at 2:54 PM, Mike Kelly wrote:

> Jan Algermissen wrote:
>> On Feb 1, 2010, at 1:38 PM, Mike Kelly wrote:
>> 
>> 
>>> I think we need to agree on the definition of 'meaning' in this 
>>> context.. because, to me, it includes more than just the current set of 
>>> available link relations, and since we're not supposed to type resources 
>>> - the only approach I can see working is predefined application flows
>>> 
>> 
>> Predefined application flows violate the hypermedia constraint and couple the server in a way that REST deliberately aims to avoid. 
>> 
> 
> Predefined application flows like AtomPub violate the hypermedia constraint?

Yes. Roy confirmed that (recent post on atom-protocol list)

> 
>> It is really as simple as this:
>> 
>> o The client needs an understanding of the set of media types that the service uses, IOW, the set of types the client has to be able to deal with. (this is what I think makes up a service type for discovery and 'governance' purposes)
>> 
> 
> I would choose to say 'set of representations' over 'set of media 
> types'.

Not getting what you mean. You cannot specify the set of representations - they can cary at will.

> Those representations will define types of link relations, which 
> in turn define the application flow(s). Over time - other links/flows 
> can be added, resources moved, media-types added etc. This is what I 
> have understood as evolveability aspect of REST wrt the hypertext 
> constraint.

Dig into this later.


> 
>> 
>> The funny thing for me was that, once actively accepting these consequences, it turns out there is really not so much that can change about a server given the above obligations. 
> 
> Ok - are you saying this is a Good Thing?

YES!! REST separates so nicely what can change from what can be kept stable in the face of evolving requirements. Its is magical - now that I see it :-)

Jan


> 
> - Mike
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Jorge:

Assume:
- You have on file several hundred photos of animals to use as captcha tests.
- You have stored metadata about the image including the "animal name"
(kitten, dog, buffalo, etc.) possibly  as EXIF w/ the file or some
other storage medium.
- You and the user-agent both support the HTML media-type (for this example).
- Upon request your server can select one of the images at random and
assign it a unique URI based on a hash of the filename and the
requesting user-agent header

Your server can then respond to requests for /i-am-human.html with a
representation that includes the URI of the image as both an <img />
tag and a hidden input to be returned by the user-agent. When the HTML
FORM is posted, the server can validate the hash to see if that photo
exists and the offered text matches the photo on file and, if it does,
validate the captcha.

The HTTP conversation could go like this:

*** REQUEST
GET /i-am-human.html HTTP/1.1
Host: www.example.org
Accept: text/html
User-Agent: common-browser/1.0

*** RESPONSE
HTTP/1.1 200 OK
Date: ...
Server: smart-server/9.0
...
Content-Type: text/html
Content-Length: nnn

....
<form method="post" action="http://www.example.org/prove-it">
  <input type="hidden" name="captcha-image"
value="http://www.example.org/captcha-images/a1s2d3f4g5.png" />
  User Name: <input type="text" name="user-name" value="" />
  Animal:   <input type="text" name="captcha-animal" value="" />
  <img src="http://www.example.org/captcha-images/a1s2d3f4g5.png"
title="What animal appears in this photo?" />
  <input type="submit" />
</form>
...


*** REQUEST
POST /prove-it HTTP/1.1
Host: www.example.org
Content-Type: application/x-www-form-urlencoded
User-Agent: common-browser/1.0

captcha-image=http%3A%2F%2Fwww.example.org%2Fcaptcha-images%2Fa1s2d3f4g5.png&user-name=Mike&captcha-animal=kitten

*** RESPONSE
HTTP/1.1 400 Bad Request
Date: ...
Server: smart-server/9.0
...
Content-Type: text/html
Content-Length: nnn

...
<p class="error">Sorry, that was not a photo of a kitten. You must not
be human.</p>
...

There are lots of possible variations on this approach.

mca
http://amundsen.com/blog/




On Mon, Feb 1, 2010 at 12:48, Jorge <george.news@...> wrote:
> Hi
>
> --- In rest-discuss@yahoogroups.com, mike amundsen <mamund@...> wrote:
>>
>> How about this:
>>
>> When a person requests the representation to fill out (the one w/ the
>> captcha rendering)
>> - generate a captcha image and create a new resource for it
>> (/captchas/a1s2d3f3g4)
>> - in the response representation, include an embed link (<img />) to the
>> generated captcha resource _and_ a hidden input that contains the same URI
>>
>> When the user POSTs the representation back, it can include a pointer to the
>> captcha resource (from the hidden input) as well as the user's input text.
>> You can use that pointer to validate the input text passed by the user.
>>
>> The images could be generated ahead of time or on deamand. The URIs could be
>> completely random or a hash of the actual captcha text to short-cut the
>> validation process. The captcha URIs can be marked as single-use and even
>> limited time-valid to cut down on flooding, etc.
>
>
> Could you please put how do you foreseen the resources?
>
> �POST --> /captchas � �return � /captchas/a1s2d3f3g4 with representation
>
> Then, how is the validation resource? and is it a POST, PUT,...?
>
> TA
>
>> mca
>> http://amundsen.com/blog/
>>
>>
>>
>> On Sat, Jan 30, 2010 at 10:07, Alexandros Marinos <al3xgr@...> wrote:
>>
>> >
>> >
>> > Hi All,
>> >
>> > I was wondering how you would implement a RESTful CAPTCHA solution,
>> > especially in the context of the strict interpretation of 'statelessness'
>> > many on this list use. I would assume the 'naive' solution would be to send
>> > a hash of the answer to the user and then use both the hash (which the user
>> > returns to the server) and the answer on the server side to see if they
>> > match. But that exposes the server to replay attacks. The approach I would
>> > take (which violates the 'strict interpretation' of statelessness) would be
>> > to create a new resource for the captcha on the server and compare the
>> > incoming answer with that, destroying the resource when done.
>> >
>> > I am unsure what approach would satisfy both requirements. My intention for
>> > starting this discussion is not to inflame, but to better understand the
>> > 'strict' statelessness POV.
>> >
>> > Thanks,
>> > Alexandros.
>> >
>> >
>> >
>>
>
>
>

Thank you for your replies.

I think both Craig and Eric agree that a collection of "links"
to resources should be returned to the client in a form that is not
simply a cut-down version of the actual resource, but is clearly a link.
Eric then goes further to suggest that by re-using a well known
specification, anybody writing a client gets the benefit of reusing
knowledge (and possibly tools) they already have.

I will look more closely at the Atom specification to see how well it
fits my situation... though I have one immediate question:

As stated originally, I wanted my representation of the Seller resource
to contain both the Seller information and the collection of links to
Accounts. I don't want the Seller representation to be a Service
Document that contains pointers to the feeds, which the client would
then have to GET separately. How would you mix one or more feeds into
the representation of a resource? Would you have something along the
lines of:
<seller .....>
    <otherInfo1 />
    <otherInfo2 />
    <feed xmlns="http://www.w3.org/2005/Atom">
      <title>Accounts</title>

      ...

      <entry>...</entry>

      <entry>...</entry>

    </feed>

</seller>

If so, what media type should be used? Neither
"application/atomserv+xml" or "application/atom+xml" seem
appropriate.

I understand the benefits of re-using a standard but worry about the
verbosity compared to a custom representation. I also wonder about the
real benefits when the client will have to be built to understand the
"foreign markup" anyway if it is to be of any use to an end
user.

I think I might be sold more on the idea if I could see an example of
this embedding of feeds into a representation or a resource.

Thank you for your time

Piers

You might to check out the draft of the "Inlining" extension for Atom:
http://tools.ietf.org/html/draft-mehta-atom-inline-01

I see it's expired as of 2009-12-31, but it might give you some ideas on how
to approach the problem.

mca
http://amundsen.com/blog/



On Mon, Feb 1, 2010 at 18:48, piers_lawson <Piers@...> wrote:

>
>
> Thank you for your replies.
>
> I think both Craig and Eric agree that a collection of "links" to resources
> should be returned to the client in a form that is not simply a cut-down
> version of the actual resource, but is clearly a link.  Eric then goes
> further to suggest that by re-using a well known specification, anybody
> writing a client gets the benefit of reusing knowledge (and possibly tools)
> they already have.
>
> I will look more closely at the Atom specification to see how well it fits
> my situation... though I have one immediate question:
>
> As stated originally, I wanted my representation of the Seller resource to
> contain both the Seller information and the collection of links to Accounts.
> I don't want the Seller representation to be a Service Document that
> contains pointers to the feeds, which the client would then have to GET
> separately. How would you mix one or more feeds into the representation of a
> resource? Would you have something along the lines of:
>
> <seller .....>
>    <otherInfo1 />
>    <otherInfo2 />
>    <feed xmlns="http://www.w3.org/2005/Atom">
>
>      <title>Accounts</title>
>
>      ...
>
>      <entry>...</entry>
>
>      <entry>...</entry>
>
>    </feed>
>
> </seller>
>
> If so, what media type should be used? Neither "application/atomserv+xml"
> or "application/atom+xml" seem appropriate.
>
> I understand the benefits of re-using a standard but worry about the
> verbosity compared to a custom representation. I also wonder about the real
> benefits when the client will have to be built to understand the "foreign
> markup" anyway if it is to be of any use to an end user.
>
> I think I might be sold more on the idea if I could see an example of this
> embedding of feeds into a representation or a resource.
>
> Thank you for your time
>
> Piers
>
>
> 

--- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
> On Feb 1, 2010, at 2:54 PM, Mike Kelly wrote:
> > Jan Algermissen wrote:
> >> On Feb 1, 2010, at 1:38 PM, Mike Kelly wrote:
> >>> I think we need to agree on the definition of 'meaning' in this 
> >>> context.. because, to me, it includes more than just the current set of 
> >>> available link relations, and since we're not supposed to type resources 
> >>> - the only approach I can see working is predefined application flows
> >>> 
> >> 
> >> Predefined application flows violate the hypermedia constraint and couple the server in a way that REST deliberately aims to avoid. 
> >> 
> > 
> > Predefined application flows like AtomPub violate the hypermedia constraint?
> 
> Yes. Roy confirmed that (recent post on atom-protocol list)


Really? Can you link to that? Was it the "MUST a collection be returned as an Atom feed?" thread?

I didn't read any of Roy's comments that way... or maybe I don't understand what you mean by "AtomPub's predefined flow".

Do you mean the Service -> Feed -> Entry hierarchy?

You said yourself in that thread that <collection> and <image> played conceptually similar roles. Isn't Page -> Image a similar two-level hierarchy? What is wrong with that?

I guess what I'm wondering is if AtomPub really defines an 
"application flow" or do client writers mistake the hierarchy for one?

Regards,

Andrew

On Feb 2, 2010, at 4:16 AM, wahbedahbe wrote:

> 
> --- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
>> On Feb 1, 2010, at 2:54 PM, Mike Kelly wrote:
>>> Jan Algermissen wrote:
>>>> On Feb 1, 2010, at 1:38 PM, Mike Kelly wrote:
>>>>> I think we need to agree on the definition of 'meaning' in this 
>>>>> context.. because, to me, it includes more than just the current set of 
>>>>> available link relations, and since we're not supposed to type resources 
>>>>> - the only approach I can see working is predefined application flows
>>>>> 
>>>> 
>>>> Predefined application flows violate the hypermedia constraint and couple the server in a way that REST deliberately aims to avoid. 
>>>> 
>>> 
>>> Predefined application flows like AtomPub violate the hypermedia constraint?
>> 
>> Yes. Roy confirmed that (recent post on atom-protocol list)
> 
> 
> Really? Can you link to that? Was it the "MUST a collection be returned as an Atom feed?" thread?

Yep. http://www.imc.org/atom-protocol/mail-archive/msg11487.html

> 
> I didn't read any of Roy's comments that way... or maybe I don't understand what you mean by "AtomPub's predefined flow".

The requirement that a GET on a collection returns an Atom feed. That is unRESTful coupling because the client must not rely on such information but react to whatever it gets at runtime.

> 
> Do you mean the Service -> Feed -> Entry hierarchy?

Yes, that's what it comes down to.

> 
> You said yourself in that thread that <collection> and <image> played conceptually similar roles. Isn't Page -> Image a similar two-level hierarchy? What is wrong with that?

<collection href=""> points to 'a collection', that is ok. But predefining the media type that comes back from the collection is not. Might well be RSS or text/uri-list


> 
> I guess what I'm wondering is if AtomPub really defines an 
> "application flow" or do client writers mistake the hierarchy for one?

A truly RESTful client would do a GET on the collection and treat any response as 'correct' from a server POV (except for non-Collection representations, for
example an audio file).

Only if we do that the server's independent evolvability is preserved.

Jan

> 
> Regards,
> 
> Andrew
> 
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

On Feb 2, 2010, at 12:48 AM, piers_lawson wrote:

> 
> 
> Thank you for your replies.
> 
> I think both Craig and Eric agree that a collection of "links" to resources should be returned to the client in a form that is not simply a cut-down version of the actual resource, but is clearly a link.  Eric then goes further to suggest that by re-using a well known specification, anybody writing a client gets the benefit of reusing knowledge (and possibly tools) they already have.
> 
> I will look more closely at the Atom specification to see how well it fits my situation... though I have one immediate question:
> 
> As stated originally, I wanted my representation of the Seller resource to contain both the Seller information and the collection of links to Accounts. I don't want the Seller representation to be a Service Document that contains pointers to the feeds, which the client would then have to GET separately. How would you mix one or more feeds into the representation of a resource? Would you have something along the lines of:
> 
> <seller .....>
> 
>    <otherInfo1 />
> 
>    <otherInfo2 />
> 
>    <feed xmlns="http://www.w3.org/2005/Atom">
>      <title>Accounts</title>
> 
>      ...
> 
>      <entry>...</entry>
> 
>      <entry>...</entry>
> 
>    </feed>
> 
> </seller>
> 
> If so, what media type should be used? Neither "application/atomserv+xml" or "application/atom+xml" seem appropriate.
> 
> I understand the benefits of re-using a standard but worry about the verbosity compared to a custom representation.

Since you have a custom <seller> anyhow, I'd - for the sake of clarity - just use custom markup for the account links, too. You might still provide an extra resource that is the collection of accounts and provide a feed for that.

e.g. 

<seller>
  ...
  <accounts href="">
    <account .....>
    <account ....>
  </accouts>
</seller>

Jan



> I also wonder about the real benefits when the client will have to be built to understand the "foreign markup" anyway if it is to be of any use to an end user.
> 
> I think I might be sold more on the idea if I could see an example of this embedding of feeds into a representation or a resource.
> 
> Thank you for your time
> 
> Piers
> 
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Jan Algermissen wrote:
> On Feb 2, 2010, at 4:16 AM, wahbedahbe wrote:
>
>   
>> --- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
>>     
>>> On Feb 1, 2010, at 2:54 PM, Mike Kelly wrote:
>>>       
>>>> Jan Algermissen wrote:
>>>>         
>>>>> On Feb 1, 2010, at 1:38 PM, Mike Kelly wrote:
>>>>>           
>>>>>> I think we need to agree on the definition of 'meaning' in this 
>>>>>> context.. because, to me, it includes more than just the current set of 
>>>>>> available link relations, and since we're not supposed to type resources 
>>>>>> - the only approach I can see working is predefined application flows
>>>>>>
>>>>>>             
>>>>> Predefined application flows violate the hypermedia constraint and couple the server in a way that REST deliberately aims to avoid. 
>>>>>
>>>>>           
>>>> Predefined application flows like AtomPub violate the hypermedia constraint?
>>>>         
>>> Yes. Roy confirmed that (recent post on atom-protocol list)
>>>       
>> Really? Can you link to that? Was it the "MUST a collection be returned as an Atom feed?" thread?
>>     
>
> Yep. http://www.imc.org/atom-protocol/mail-archive/msg11487.html
>   

That post is about over-specification, not predefinition. And leads me 
to ask - What is an 'adequate specification', if not predefinition?

- Mike

On Feb 2, 2010, at 11:25 AM, Mike Kelly wrote:

> Jan Algermissen wrote:
>> On Feb 2, 2010, at 4:16 AM, wahbedahbe wrote:
>> 
>> 
>>> --- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
>>> 
>>>> On Feb 1, 2010, at 2:54 PM, Mike Kelly wrote:
>>>> 
>>>>> Jan Algermissen wrote:
>>>>> 
>>>>>> On Feb 1, 2010, at 1:38 PM, Mike Kelly wrote:
>>>>>> 
>>>>>>> I think we need to agree on the definition of 'meaning' in this 
>>>>>>> context.. because, to me, it includes more than just the current set of 
>>>>>>> available link relations, and since we're not supposed to type resources 
>>>>>>> - the only approach I can see working is predefined application flows
>>>>>>> 
>>>>>>> 
>>>>>> Predefined application flows violate the hypermedia constraint and couple the server in a way that REST deliberately aims to avoid. 
>>>>>> 
>>>>>> 
>>>>> Predefined application flows like AtomPub violate the hypermedia constraint?
>>>>> 
>>>> Yes. Roy confirmed that (recent post on atom-protocol list)
>>>> 
>>> Really? Can you link to that? Was it the "MUST a collection be returned as an Atom feed?" thread?
>>> 
>> 
>> Yep. http://www.imc.org/atom-protocol/mail-archive/msg11487.html
>> 
> 
> That post is about over-specification, not predefinition. And leads me 
> to ask - What is an 'adequate specification', if not predefinition?

I understood Roy to be saying that it is an over-specifiction that AtomPub requires GETs on collections to return an Atom feed.

Such a predefinition is an over-specification in RESTland.

Jan

> 
> - Mike
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Jan Algermissen wrote:
> On Feb 2, 2010, at 11:25 AM, Mike Kelly wrote:
>
>   
>> Jan Algermissen wrote:
>>     
>>> On Feb 2, 2010, at 4:16 AM, wahbedahbe wrote:
>>>
>>>
>>>       
>>>> --- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
>>>>
>>>>         
>>>>> On Feb 1, 2010, at 2:54 PM, Mike Kelly wrote:
>>>>>
>>>>>           
>>>>>> Jan Algermissen wrote:
>>>>>>
>>>>>>             
>>>>>>> On Feb 1, 2010, at 1:38 PM, Mike Kelly wrote:
>>>>>>>
>>>>>>>               
>>>>>>>> I think we need to agree on the definition of 'meaning' in this 
>>>>>>>> context.. because, to me, it includes more than just the current set of 
>>>>>>>> available link relations, and since we're not supposed to type resources 
>>>>>>>> - the only approach I can see working is predefined application flows
>>>>>>>>
>>>>>>>>
>>>>>>>>                 
>>>>>>> Predefined application flows violate the hypermedia constraint and couple the server in a way that REST deliberately aims to avoid. 
>>>>>>>
>>>>>>>
>>>>>>>               
>>>>>> Predefined application flows like AtomPub violate the hypermedia constraint?
>>>>>>
>>>>>>             
>>>>> Yes. Roy confirmed that (recent post on atom-protocol list)
>>>>>
>>>>>           
>>>> Really? Can you link to that? Was it the "MUST a collection be returned as an Atom feed?" thread?
>>>>
>>>>         
>>> Yep. http://www.imc.org/atom-protocol/mail-archive/msg11487.html
>>>
>>>       
>> That post is about over-specification, not predefinition. And leads me 
>> to ask - What is an 'adequate specification', if not predefinition?
>>     
>
> I understood Roy to be saying that it is an over-specifiction that AtomPub requires GETs on collections to return an Atom feed.
>
> Such a predefinition is an over-specification in RESTland.
>
> Jan
>   

Maybe so, but the use of term "over" specification implies that there is 
infact an appropriate degree of specification i.e. a predefined flow 
with a more suitable level of liberalism.

- Mike

When a client sends a POST request and receives a 201 Created...

a) is the POST response body the steady state

b) is it implied by HTTP spec that the client will do a GET on the Location and is that the steady state?

c) is this up to the media type that contained the link to the POST-accepting resource?



For other return codes I think this:

200 Ok        - steady state is the POST response
202 Accepted  - steady state is available at the link provided by the body of the 202 response
303 See Other - steady state is available ta resource that the Location points to

Jan

Boing... any idea?

On 01/02/2010 10:28, George wrote:
>
>
> Hi,
>
> Let's try to explain it a little further.
>
> On 01/02/2010 9:02, Jan Algermissen wrote:
>  > George,
>  >
>  > On Jan 30, 2010, at 1:38 PM, George wrote:
>  >
>  >> Hi,
>  >>
>  >> I'm planning to develop a webservice, and I like to try the RESTful
>  >> architecture.
>  >>
>  >> The service is about downloading some data from the server to a device
>  >> attached on the local computer. The client need to retrieve the command
>  >> from the server and then send the response of the device to the server
>  >> to check its validity. Then the server says if it is ok or not.
>  >
>  > I think I do not understand what you are up to. Why does the client
> fetch the command for the device from the server?
>
> The system is foreseen to control a hardware device. The issue is that
> the device only accepts a subset of commands based on some cryptographic
> features.
>
> I don't want the command set and the cryptographic keys to be on the
> client, as this way I have to replicate the keys on every client and the
> security can be comprised.
>
> Each command is encrypted with different keys depending on the device it
> is directed to. So the issue is first is that the server needs to know
> the device as to open the session with the correct set of keys. After
> that, the client get the command (encripted and maced with server keys),
> this command is sent to the device who will response. The response has
> some crypto stuff that need to be check on the server. Then the client
> get an ACK or NACK depending on the correct answer from the device
> (whether the command is well executed or not, or whether the device owns
> the correct set of keys and it not a fake device).
>
>  >
>  >
>  >
>  >>
>  >> Device client Server
>  >> ----> Get command
>  >> <-----<-----
>  >>
>  >> ----> ----> Response from device
>  >> <----- Response from server indicating
>  >> if it is ok or not the execution
>  >>
>  >> It would be like: client calls authenticate of device. then the server
>  >> sends the command to be sent to the device for authentication.
>  >
>  > HTTP authentication is orthogonal. Use one of the HTTP standard
> authentication solutions.
>
> Authentication is done based on the crypto protocol that I explained above.
>
>  >
>  >
>  >> The
>  >> client send this command to the device and the response is sent back to
>  >> the server. The server then replies.
>  >>
>  >> I have thought on:
>  >> /device/{id} as resource
>  >> /device/{id}/authenticate
>  >> GET will retrieve the command and blank state
>  >> <command> value</command>
>  >> <state> not defined</command>
>  >> PUT will send the response and get the real state
>  >> ---> <response> value</response>
>  >> <---<state> not defined</command>
>  >>
>  >> I don't know if this is REST. Is it better to create another
> resource as:
>  >> /device/{id}/authenticate/command (only GET available)
>  >> /device/{id}/authenticate/response (only PUT available)
>  >> /device/{id}/authenticate (only GET avaliable for status)
>  >>
>  >> Any help is welcome.
>  >
>  > Can you explain your requirements? I am having trouble understanding
> what you are trying to do.
>
> The issue is that I need to get a command and then check the answer from
> that command. This will be done in 2 steps, and I don't know how to map
> that into resources.
>
> Thanks... hope now is clearer.
>
> CU
> Jorge
>
>  > Jan
>  >
>  >
>  >
>  >> TA
>  >>
>  >>
>  >>
>  >>
>  >>
>  >>
>  >>
>  >>
>  >> ------------------------------------
>  >>
>  >> Yahoo! Groups Links
>  >>
>  >>
>  >>
>  >
>  > -----------------------------------
>  > Jan Algermissen, Consultant
>  >
>  > Mail: algermissen@... <mailto:algermissen%40acm.org>
>  > Blog: http://www.nordsc.com/blog/ <http://www.nordsc.com/blog/>
>  > Work: http://www.nordsc.com/ <http://www.nordsc.com/>
>  > -----------------------------------
>  >
>  >
>  >
>
> 

I just read this on the diagonal, but it seems similar to what SyncML
does, is that the case?


_________________________________________________

Melhores cumprimentos / Beir beannacht / Best regards

Ant�nio Manuel dos Santos Mota

http://card.ly/amsmota
_________________________________________________




2010/2/2 George <george.news@...>:
> Boing... any idea?
>
> On 01/02/2010 10:28, George wrote:
>>
>>
>> Hi,
>>
>> Let's try to explain it a little further.
>>
>> On 01/02/2010 9:02, Jan Algermissen wrote:
>> �> George,
>> �>
>> �> On Jan 30, 2010, at 1:38 PM, George wrote:
>> �>
>> �>> Hi,
>> �>>
>> �>> I'm planning to develop a webservice, and I like to try the RESTful
>> �>> architecture.
>> �>>
>> �>> The service is about downloading some data from the server to a device
>> �>> attached on the local computer. The client need to retrieve the command
>> �>> from the server and then send the response of the device to the server
>> �>> to check its validity. Then the server says if it is ok or not.
>> �>
>> �> I think I do not understand what you are up to. Why does the client
>> fetch the command for the device from the server?
>>
>> The system is foreseen to control a hardware device. The issue is that
>> the device only accepts a subset of commands based on some cryptographic
>> features.
>>
>> I don't want the command set and the cryptographic keys to be on the
>> client, as this way I have to replicate the keys on every client and the
>> security can be comprised.
>>
>> Each command is encrypted with different keys depending on the device it
>> is directed to. So the issue is first is that the server needs to know
>> the device as to open the session with the correct set of keys. After
>> that, the client get the command (encripted and maced with server keys),
>> this command is sent to the device who will response. The response has
>> some crypto stuff that need to be check on the server. Then the client
>> get an ACK or NACK depending on the correct answer from the device
>> (whether the command is well executed or not, or whether the device owns
>> the correct set of keys and it not a fake device).
>>
>> �>
>> �>
>> �>
>> �>>
>> �>> Device client Server
>> �>> ----> Get command
>> �>> <-----<-----
>> �>>
>> �>> ----> ----> Response from device
>> �>> <----- Response from server indicating
>> �>> if it is ok or not the execution
>> �>>
>> �>> It would be like: client calls authenticate of device. then the server
>> �>> sends the command to be sent to the device for authentication.
>> �>
>> �> HTTP authentication is orthogonal. Use one of the HTTP standard
>> authentication solutions.
>>
>> Authentication is done based on the crypto protocol that I explained above.
>>
>> �>
>> �>
>> �>> The
>> �>> client send this command to the device and the response is sent back to
>> �>> the server. The server then replies.
>> �>>
>> �>> I have thought on:
>> �>> /device/{id} as resource
>> �>> /device/{id}/authenticate
>> �>> GET will retrieve the command and blank state
>> �>> <command> value</command>
>> �>> <state> not defined</command>
>> �>> PUT will send the response and get the real state
>> �>> ---> <response> value</response>
>> �>> <---<state> not defined</command>
>> �>>
>> �>> I don't know if this is REST. Is it better to create another
>> resource as:
>> �>> /device/{id}/authenticate/command (only GET available)
>> �>> /device/{id}/authenticate/response (only PUT available)
>> �>> /device/{id}/authenticate (only GET avaliable for status)
>> �>>
>> �>> Any help is welcome.
>> �>
>> �> Can you explain your requirements? I am having trouble understanding
>> what you are trying to do.
>>
>> The issue is that I need to get a command and then check the answer from
>> that command. This will be done in 2 steps, and I don't know how to map
>> that into resources.
>>
>> Thanks... hope now is clearer.
>>
>> CU
>> Jorge
>>
>> �> Jan
>> �>
>> �>
>> �>
>> �>> TA
>> �>>
>> �>>
>> �>>
>> �>>
>> �>>
>> �>>
>> �>>
>> �>>
>> �>> ------------------------------------
>> �>>
>> �>> Yahoo! Groups Links
>> �>>
>> �>>
>> �>>
>> �>
>> �> -----------------------------------
>> �> Jan Algermissen, Consultant
>> �>
>> �> Mail: algermissen@... <mailto:algermissen%40acm.org>
>> �> Blog: http://www.nordsc.com/blog/ <http://www.nordsc.com/blog/>
>> �> Work: http://www.nordsc.com/ <http://www.nordsc.com/>
>> �> -----------------------------------
>> �>
>> �>
>> �>
>>
>>
>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

On 02/02/2010 14:31, Ant�nio Mota wrote:
> I just read this on the diagonal, but it seems similar to what SyncML
> does, is that the case?

SyncML seems to be used to syncronized devices' (mobiles, handhelds,..) 
information, such as contacts,... My case is not such a thing, as the 
commands are for instance RS232 commands to be sent to a local device.

Thanks. Anyway I will read a little further SyncML (curiosity)

See you



>
> _________________________________________________
>
> Melhores cumprimentos / Beir beannacht / Best regards
>
> Ant�nio Manuel dos Santos Mota
>
> http://card.ly/amsmota
> _________________________________________________
>
>
>
>
> 2010/2/2 George<george.news@...>:
>> Boing... any idea?
>>
>> On 01/02/2010 10:28, George wrote:
>>>
>>>
>>> Hi,
>>>
>>> Let's try to explain it a little further.
>>>
>>> On 01/02/2010 9:02, Jan Algermissen wrote:
>>>   >  George,
>>>   >
>>>   >  On Jan 30, 2010, at 1:38 PM, George wrote:
>>>   >
>>>   >>  Hi,
>>>   >>
>>>   >>  I'm planning to develop a webservice, and I like to try the RESTful
>>>   >>  architecture.
>>>   >>
>>>   >>  The service is about downloading some data from the server to a device
>>>   >>  attached on the local computer. The client need to retrieve the command
>>>   >>  from the server and then send the response of the device to the server
>>>   >>  to check its validity. Then the server says if it is ok or not.
>>>   >
>>>   >  I think I do not understand what you are up to. Why does the client
>>> fetch the command for the device from the server?
>>>
>>> The system is foreseen to control a hardware device. The issue is that
>>> the device only accepts a subset of commands based on some cryptographic
>>> features.
>>>
>>> I don't want the command set and the cryptographic keys to be on the
>>> client, as this way I have to replicate the keys on every client and the
>>> security can be comprised.
>>>
>>> Each command is encrypted with different keys depending on the device it
>>> is directed to. So the issue is first is that the server needs to know
>>> the device as to open the session with the correct set of keys. After
>>> that, the client get the command (encripted and maced with server keys),
>>> this command is sent to the device who will response. The response has
>>> some crypto stuff that need to be check on the server. Then the client
>>> get an ACK or NACK depending on the correct answer from the device
>>> (whether the command is well executed or not, or whether the device owns
>>> the correct set of keys and it not a fake device).
>>>
>>>   >
>>>   >
>>>   >
>>>   >>
>>>   >>  Device client Server
>>>   >>  ---->  Get command
>>>   >>  <-----<-----
>>>   >>
>>>   >>  ---->  ---->  Response from device
>>>   >>  <----- Response from server indicating
>>>   >>  if it is ok or not the execution
>>>   >>
>>>   >>  It would be like: client calls authenticate of device. then the server
>>>   >>  sends the command to be sent to the device for authentication.
>>>   >
>>>   >  HTTP authentication is orthogonal. Use one of the HTTP standard
>>> authentication solutions.
>>>
>>> Authentication is done based on the crypto protocol that I explained above.
>>>
>>>   >
>>>   >
>>>   >>  The
>>>   >>  client send this command to the device and the response is sent back to
>>>   >>  the server. The server then replies.
>>>   >>
>>>   >>  I have thought on:
>>>   >>  /device/{id} as resource
>>>   >>  /device/{id}/authenticate
>>>   >>  GET will retrieve the command and blank state
>>>   >>  <command>  value</command>
>>>   >>  <state>  not defined</command>
>>>   >>  PUT will send the response and get the real state
>>>   >>  --->  <response>  value</response>
>>>   >>  <---<state>  not defined</command>
>>>   >>
>>>   >>  I don't know if this is REST. Is it better to create another
>>> resource as:
>>>   >>  /device/{id}/authenticate/command (only GET available)
>>>   >>  /device/{id}/authenticate/response (only PUT available)
>>>   >>  /device/{id}/authenticate (only GET avaliable for status)
>>>   >>
>>>   >>  Any help is welcome.
>>>   >
>>>   >  Can you explain your requirements? I am having trouble understanding
>>> what you are trying to do.
>>>
>>> The issue is that I need to get a command and then check the answer from
>>> that command. This will be done in 2 steps, and I don't know how to map
>>> that into resources.
>>>
>>> Thanks... hope now is clearer.
>>>
>>> CU
>>> Jorge
>>>
>>>   >  Jan
>>>   >
>>>   >
>>>   >
>>>   >>  TA
>>>   >>
>>>   >>
>>>   >>
>>>   >>
>>>   >>
>>>   >>
>>>   >>
>>>   >>
>>>   >>  ------------------------------------
>>>   >>
>>>   >>  Yahoo! Groups Links
>>>   >>
>>>   >>
>>>   >>
>>>   >
>>>   >  -----------------------------------
>>>   >  Jan Algermissen, Consultant
>>>   >
>>>   >  Mail: algermissen@...<mailto:algermissen%40acm.org>
>>>   >  Blog: http://www.nordsc.com/blog/<http://www.nordsc.com/blog/>
>>>   >  Work: http://www.nordsc.com/<http://www.nordsc.com/>
>>>   >  -----------------------------------
>>>   >
>>>   >
>>>   >
>>>
>>>
>>
>>
>>
>> ------------------------------------
>>
>> Yahoo! Groups Links
>>
>>
>>
>>
>

--- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
>
> When a client sends a POST request and receives a 201 Created...
> 
> a) is the POST response body the steady state
> 
> b) is it implied by HTTP spec that the client will do a GET on the Location and is that the steady state?
> 
> c) is this up to the media type that contained the link to the POST-accepting resource?
> 
> 
> 
> For other return codes I think this:
> 
> 200 Ok        - steady state is the POST response
> 202 Accepted  - steady state is available at the link provided by the body of the 202 response
> 303 See Other - steady state is available ta resource that the Location points to
> 
> Jan
>

I think the HTTP spec is pretty clear that 201 responses SHOULD have a body which constitutes your steady state.
Section 9.5:
   If a resource has been created on the origin server, the response
   SHOULD be 201 (Created) and contain an entity which describes the
   status of the request and refers to the new resource, and a  
   Location header (see section 14.30)
Section 10.2.2:
   The newly created resource can be referenced by the URI(s)
   returned in the entity of the response, with the most specific URI
   for the resource given by a Location header field. The response
   SHOULD include an entity containing a list of resource
   characteristics and location(s) from which the user or user agent 
   can choose the one most appropriate. The entity format is   
   specified by the media type given in the Content-Type header field.

I've always considered the Location header in 201 responses as information for intermediaries rather than the driver of application state. But I know I'm in the minority on that: a lot of people don't even have a body in their 201 responses (which to me is a violation of the spec).
Regards,

Andrew

--- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
>
> 
> On Feb 2, 2010, at 4:16 AM, wahbedahbe wrote:
> 
> > 
> > --- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@> wrote:
> >> On Feb 1, 2010, at 2:54 PM, Mike Kelly wrote:
> >>> Jan Algermissen wrote:
> >>>> On Feb 1, 2010, at 1:38 PM, Mike Kelly wrote:
> >>>>> I think we need to agree on the definition of 'meaning' in this 
> >>>>> context.. because, to me, it includes more than just the current set of 
> >>>>> available link relations, and since we're not supposed to type resources 
> >>>>> - the only approach I can see working is predefined application flows
> >>>>> 
> >>>> 
> >>>> Predefined application flows violate the hypermedia constraint and couple the server in a way that REST deliberately aims to avoid. 
> >>>> 
> >>> 
> >>> Predefined application flows like AtomPub violate the hypermedia constraint?
> >> 
> >> Yes. Roy confirmed that (recent post on atom-protocol list)
> > 
> > 
> > Really? Can you link to that? Was it the "MUST a collection be returned as an Atom feed?" thread?
> 
> Yep. http://www.imc.org/atom-protocol/mail-archive/msg11487.html
> 
> > 
> > I didn't read any of Roy's comments that way... or maybe I don't understand what you mean by "AtomPub's predefined flow".
> 
> The requirement that a GET on a collection returns an Atom feed. That is unRESTful coupling because the client must not rely on such information but react to whatever it gets at runtime.
> 
> > 
> > Do you mean the Service -> Feed -> Entry hierarchy?
> 
> Yes, that's what it comes down to.
> 
> > 
> > You said yourself in that thread that <collection> and <image> played conceptually similar roles. Isn't Page -> Image a similar two-level hierarchy? What is wrong with that?
> 
> <collection href=""> points to 'a collection', that is ok. But predefining the media type that comes back from the collection is not. Might well be RSS or text/uri-list
> 
> 
> > 
> > I guess what I'm wondering is if AtomPub really defines an 
> > "application flow" or do client writers mistake the hierarchy for one?
> 
> A truly RESTful client would do a GET on the collection and treat any response as 'correct' from a server POV (except for non-Collection representations, for
> example an audio file).
> 
> Only if we do that the server's independent evolvability is preserved.
> 

Ok... agree on the above, but how do you define 'collection'? To me it's something that has a set of 'entries'. So you get the hierarchy don't you? A 'good' client can/should be flexible on the media types though (and the spec shouldn't try to restrict them). Perhaps the variability in media type means that the entries may be exclusively inline for some representations which just means that the hierarchy might not map to your addressable resources, but it's still there.


Andrew

But SHOULD is not SHALL, is a recommendation not a imposition... So not
having a body on a 201 could not be considered a violation of the spec...
Wich indeed turns things more complicated in determining what a steady-state
should be...


_________________________________________________

Melhores cumprimentos / Beir beannacht / Best regards

Ant�nio Manuel dos Santos Mota

http://card.ly/amsmota
_________________________________________________



2010/2/2 wahbedahbe <andrew.wahbe@...>

>
>
>
>
> --- In rest-discuss@yahoogroups.com <rest-discuss%40yahoogroups.com>, Jan
> Algermissen <algermissen1971@...> wrote:
> >
> > When a client sends a POST request and receives a 201 Created...
> >
> > a) is the POST response body the steady state
> >
> > b) is it implied by HTTP spec that the client will do a GET on the
> Location and is that the steady state?
> >
> > c) is this up to the media type that contained the link to the
> POST-accepting resource?
> >
> >
> >
> > For other return codes I think this:
> >
> > 200 Ok - steady state is the POST response
> > 202 Accepted - steady state is available at the link provided by the body
> of the 202 response
> > 303 See Other - steady state is available ta resource that the Location
> points to
> >
> > Jan
> >
>
> I think the HTTP spec is pretty clear that 201 responses SHOULD have a body
> which constitutes your steady state.
> Section 9.5:
> If a resource has been created on the origin server, the response
> SHOULD be 201 (Created) and contain an entity which describes the
> status of the request and refers to the new resource, and a
> Location header (see section 14.30)
> Section 10.2.2:
> The newly created resource can be referenced by the URI(s)
> returned in the entity of the response, with the most specific URI
> for the resource given by a Location header field. The response
> SHOULD include an entity containing a list of resource
> characteristics and location(s) from which the user or user agent
> can choose the one most appropriate. The entity format is
> specified by the media type given in the Content-Type header field.
>
> I've always considered the Location header in 201 responses as information
> for intermediaries rather than the driver of application state. But I know
> I'm in the minority on that: a lot of people don't even have a body in their
> 201 responses (which to me is a violation of the spec).
> Regards,
>
> Andrew
>
>  
>

Well, basically yes, is for synchronizing devices, but can be extended
to other things. For example, we use (among other things) the Alert
messages to pass what is called Command&Control messages between two
systems.

Now this is quite incompatible with the idea of REST, because SyncML
is based on Command Elements, it's not resource oriented. What you can
do is to use SyncML as payloads of REST messages, like you'll do with
any other media-type, and let the service implementations deal with
the SyncML itself.

But even if this doesn't apply to your scenario, reading the sepc MAY
give you some good ideas...

_________________________________________________

Melhores cumprimentos / Beir beannacht / Best regards

Ant�nio Manuel dos Santos Mota

http://card.ly/amsmota
_________________________________________________




2010/2/2 George <george.news@...>:
>
> On 02/02/2010 14:31, Ant�nio Mota wrote:
>>
>> I just read this on the diagonal, but it seems similar to what SyncML
>> does, is that the case?
>
> SyncML seems to be used to syncronized devices' (mobiles, handhelds,..) information, such as contacts,... My case is not such a thing, as the commands are for instance RS232 commands to be sent to a local device.
>
> Thanks. Anyway I will read a little further SyncML (curiosity)
>
> See you
>
>
>
>>
>> _________________________________________________
>>
>> Melhores cumprimentos / Beir beannacht / Best regards
>>
>> Ant�nio Manuel dos Santos Mota
>>
>> http://card.ly/amsmota
>> _________________________________________________
>>
>>
>>
>>
>> 2010/2/2 George<george.news@...>:
>>>
>>> Boing... any idea?
>>>
>>> On 01/02/2010 10:28, George wrote:
>>>>
>>>>
>>>> Hi,
>>>>
>>>> Let's try to explain it a little further.
>>>>
>>>> On 01/02/2010 9:02, Jan Algermissen wrote:
>>>> �> �George,
>>>> �>
>>>> �> �On Jan 30, 2010, at 1:38 PM, George wrote:
>>>> �>
>>>> �>> �Hi,
>>>> �>>
>>>> �>> �I'm planning to develop a webservice, and I like to try the RESTful
>>>> �>> �architecture.
>>>> �>>
>>>> �>> �The service is about downloading some data from the server to a device
>>>> �>> �attached on the local computer. The client need to retrieve the command
>>>> �>> �from the server and then send the response of the device to the server
>>>> �>> �to check its validity. Then the server says if it is ok or not.
>>>> �>
>>>> �> �I think I do not understand what you are up to. Why does the client
>>>> fetch the command for the device from the server?
>>>>
>>>> The system is foreseen to control a hardware device. The issue is that
>>>> the device only accepts a subset of commands based on some cryptographic
>>>> features.
>>>>
>>>> I don't want the command set and the cryptographic keys to be on the
>>>> client, as this way I have to replicate the keys on every client and the
>>>> security can be comprised.
>>>>
>>>> Each command is encrypted with different keys depending on the device it
>>>> is directed to. So the issue is first is that the server needs to know
>>>> the device as to open the session with the correct set of keys. After
>>>> that, the client get the command (encripted and maced with server keys),
>>>> this command is sent to the device who will response. The response has
>>>> some crypto stuff that need to be check on the server. Then the client
>>>> get an ACK or NACK depending on the correct answer from the device
>>>> (whether the command is well executed or not, or whether the device owns
>>>> the correct set of keys and it not a fake device).
>>>>
>>>> �>
>>>> �>
>>>> �>
>>>> �>>
>>>> �>> �Device client Server
>>>> �>> �----> �Get command
>>>> �>> �<-----<-----
>>>> �>>
>>>> �>> �----> �----> �Response from device
>>>> �>> �<----- Response from server indicating
>>>> �>> �if it is ok or not the execution
>>>> �>>
>>>> �>> �It would be like: client calls authenticate of device. then the server
>>>> �>> �sends the command to be sent to the device for authentication.
>>>> �>
>>>> �> �HTTP authentication is orthogonal. Use one of the HTTP standard
>>>> authentication solutions.
>>>>
>>>> Authentication is done based on the crypto protocol that I explained above.
>>>>
>>>> �>
>>>> �>
>>>> �>> �The
>>>> �>> �client send this command to the device and the response is sent back to
>>>> �>> �the server. The server then replies.
>>>> �>>
>>>> �>> �I have thought on:
>>>> �>> �/device/{id} as resource
>>>> �>> �/device/{id}/authenticate
>>>> �>> �GET will retrieve the command and blank state
>>>> �>> �<command> �value</command>
>>>> �>> �<state> �not defined</command>
>>>> �>> �PUT will send the response and get the real state
>>>> �>> �---> �<response> �value</response>
>>>> �>> �<---<state> �not defined</command>
>>>> �>>
>>>> �>> �I don't know if this is REST. Is it better to create another
>>>> resource as:
>>>> �>> �/device/{id}/authenticate/command (only GET available)
>>>> �>> �/device/{id}/authenticate/response (only PUT available)
>>>> �>> �/device/{id}/authenticate (only GET avaliable for status)
>>>> �>>
>>>> �>> �Any help is welcome.
>>>> �>
>>>> �> �Can you explain your requirements? I am having trouble understanding
>>>> what you are trying to do.
>>>>
>>>> The issue is that I need to get a command and then check the answer from
>>>> that command. This will be done in 2 steps, and I don't know how to map
>>>> that into resources.
>>>>
>>>> Thanks... hope now is clearer.
>>>>
>>>> CU
>>>> Jorge
>>>>
>>>> �> �Jan
>>>> �>
>>>> �>
>>>> �>
>>>> �>> �TA
>>>> �>>
>>>> �>>
>>>> �>>
>>>> �>>
>>>> �>>
>>>> �>>
>>>> �>>
>>>> �>>
>>>> �>> �------------------------------------
>>>> �>>
>>>> �>> �Yahoo! Groups Links
>>>> �>>
>>>> �>>
>>>> �>>
>>>> �>
>>>> �> �-----------------------------------
>>>> �> �Jan Algermissen, Consultant
>>>> �>
>>>> �> �Mail: algermissen@...<mailto:algermissen%40acm.org>
>>>> �> �Blog: http://www.nordsc.com/blog/<http://www.nordsc.com/blog/>
>>>> �> �Work: http://www.nordsc.com/<http://www.nordsc.com/>
>>>> �> �-----------------------------------
>>>> �>
>>>> �>
>>>> �>
>>>>
>>>>
>>>
>>>
>>>
>>> ------------------------------------
>>>
>>> Yahoo! Groups Links
>>>
>>>
>>>
>>>
>>
>
>

I'll give it a try. I though I could make it using REST approach, but it 
seems it is not gonna be possible.

Let's read and see if a flash comes ;)

See you


On 02/02/2010 18:10, Ant�nio Mota wrote:
> Well, basically yes, is for synchronizing devices, but can be extended
> to other things. For example, we use (among other things) the Alert
> messages to pass what is called Command&Control messages between two
> systems.
>
> Now this is quite incompatible with the idea of REST, because SyncML
> is based on Command Elements, it's not resource oriented. What you can
> do is to use SyncML as payloads of REST messages, like you'll do with
> any other media-type, and let the service implementations deal with
> the SyncML itself.
>
> But even if this doesn't apply to your scenario, reading the sepc MAY
> give you some good ideas...
>
> _________________________________________________
>
> Melhores cumprimentos / Beir beannacht / Best regards
>
> Ant�nio Manuel dos Santos Mota
>
> http://card.ly/amsmota
> _________________________________________________
>
>
>
>
> 2010/2/2 George<george.news@...>:
>>
>> On 02/02/2010 14:31, Ant�nio Mota wrote:
>>>
>>> I just read this on the diagonal, but it seems similar to what SyncML
>>> does, is that the case?
>>
>> SyncML seems to be used to syncronized devices' (mobiles, handhelds,..) information, such as contacts,... My case is not such a thing, as the commands are for instance RS232 commands to be sent to a local device.
>>
>> Thanks. Anyway I will read a little further SyncML (curiosity)
>>
>> See you
>>
>>
>>
>>>
>>> _________________________________________________
>>>
>>> Melhores cumprimentos / Beir beannacht / Best regards
>>>
>>> Ant�nio Manuel dos Santos Mota
>>>
>>> http://card.ly/amsmota
>>> _________________________________________________
>>>
>>>
>>>
>>>
>>> 2010/2/2 George<george.news@...>:
>>>>
>>>> Boing... any idea?
>>>>
>>>> On 01/02/2010 10:28, George wrote:
>>>>>
>>>>>
>>>>> Hi,
>>>>>
>>>>> Let's try to explain it a little further.
>>>>>
>>>>> On 01/02/2010 9:02, Jan Algermissen wrote:
>>>>>   >    George,
>>>>>   >
>>>>>   >    On Jan 30, 2010, at 1:38 PM, George wrote:
>>>>>   >
>>>>>   >>    Hi,
>>>>>   >>
>>>>>   >>    I'm planning to develop a webservice, and I like to try the RESTful
>>>>>   >>    architecture.
>>>>>   >>
>>>>>   >>    The service is about downloading some data from the server to a device
>>>>>   >>    attached on the local computer. The client need to retrieve the command
>>>>>   >>    from the server and then send the response of the device to the server
>>>>>   >>    to check its validity. Then the server says if it is ok or not.
>>>>>   >
>>>>>   >    I think I do not understand what you are up to. Why does the client
>>>>> fetch the command for the device from the server?
>>>>>
>>>>> The system is foreseen to control a hardware device. The issue is that
>>>>> the device only accepts a subset of commands based on some cryptographic
>>>>> features.
>>>>>
>>>>> I don't want the command set and the cryptographic keys to be on the
>>>>> client, as this way I have to replicate the keys on every client and the
>>>>> security can be comprised.
>>>>>
>>>>> Each command is encrypted with different keys depending on the device it
>>>>> is directed to. So the issue is first is that the server needs to know
>>>>> the device as to open the session with the correct set of keys. After
>>>>> that, the client get the command (encripted and maced with server keys),
>>>>> this command is sent to the device who will response. The response has
>>>>> some crypto stuff that need to be check on the server. Then the client
>>>>> get an ACK or NACK depending on the correct answer from the device
>>>>> (whether the command is well executed or not, or whether the device owns
>>>>> the correct set of keys and it not a fake device).
>>>>>
>>>>>   >
>>>>>   >
>>>>>   >
>>>>>   >>
>>>>>   >>    Device client Server
>>>>>   >>    ---->    Get command
>>>>>   >>    <-----<-----
>>>>>   >>
>>>>>   >>    ---->    ---->    Response from device
>>>>>   >>    <----- Response from server indicating
>>>>>   >>    if it is ok or not the execution
>>>>>   >>
>>>>>   >>    It would be like: client calls authenticate of device. then the server
>>>>>   >>    sends the command to be sent to the device for authentication.
>>>>>   >
>>>>>   >    HTTP authentication is orthogonal. Use one of the HTTP standard
>>>>> authentication solutions.
>>>>>
>>>>> Authentication is done based on the crypto protocol that I explained above.
>>>>>
>>>>>   >
>>>>>   >
>>>>>   >>    The
>>>>>   >>    client send this command to the device and the response is sent back to
>>>>>   >>    the server. The server then replies.
>>>>>   >>
>>>>>   >>    I have thought on:
>>>>>   >>    /device/{id} as resource
>>>>>   >>    /device/{id}/authenticate
>>>>>   >>    GET will retrieve the command and blank state
>>>>>   >>    <command>    value</command>
>>>>>   >>    <state>    not defined</command>
>>>>>   >>    PUT will send the response and get the real state
>>>>>   >>    --->    <response>    value</response>
>>>>>   >>    <---<state>    not defined</command>
>>>>>   >>
>>>>>   >>    I don't know if this is REST. Is it better to create another
>>>>> resource as:
>>>>>   >>    /device/{id}/authenticate/command (only GET available)
>>>>>   >>    /device/{id}/authenticate/response (only PUT available)
>>>>>   >>    /device/{id}/authenticate (only GET avaliable for status)
>>>>>   >>
>>>>>   >>    Any help is welcome.
>>>>>   >
>>>>>   >    Can you explain your requirements? I am having trouble understanding
>>>>> what you are trying to do.
>>>>>
>>>>> The issue is that I need to get a command and then check the answer from
>>>>> that command. This will be done in 2 steps, and I don't know how to map
>>>>> that into resources.
>>>>>
>>>>> Thanks... hope now is clearer.
>>>>>
>>>>> CU
>>>>> Jorge
>>>>>
>>>>>   >    Jan
>>>>>   >
>>>>>   >
>>>>>   >
>>>>>   >>    TA
>>>>>   >>
>>>>>   >>
>>>>>   >>
>>>>>   >>
>>>>>   >>
>>>>>   >>
>>>>>   >>
>>>>>   >>
>>>>>   >>    ------------------------------------
>>>>>   >>
>>>>>   >>    Yahoo! Groups Links
>>>>>   >>
>>>>>   >>
>>>>>   >>
>>>>>   >
>>>>>   >    -----------------------------------
>>>>>   >    Jan Algermissen, Consultant
>>>>>   >
>>>>>   >    Mail: algermissen@...<mailto:algermissen%40acm.org>
>>>>>   >    Blog: http://www.nordsc.com/blog/<http://www.nordsc.com/blog/>
>>>>>   >    Work: http://www.nordsc.com/<http://www.nordsc.com/>
>>>>>   >    -----------------------------------
>>>>>   >
>>>>>   >
>>>>>   >
>>>>>
>>>>>
>>>>
>>>>
>>>>
>>>> ------------------------------------
>>>>
>>>> Yahoo! Groups Links
>>>>
>>>>
>>>>
>>>>
>>>
>>
>>
>

Mike, thank you for pointing out the draft inlining spec... it was interesting.

Jan, I started off the thread suggesting a format similar to the one that you put forward as one of my alternatives. I have been convinced by the idea that really the collection should not contain Account elements but some sort of link. The inlining idea is good in that it formalises combining a link with some data from the target resource.... at least it would be if the spec  had moved forward from being a draft ;-)

However, what I'm really pushing for is an example of publishing a feed (or even feeds) within other content, for example within the seller element from my last post. If I end up with something similar to my last post (i.e. a seller element that contains a feed element) I'm back to a custom vocabulary... at which point I can't see the advantage of using Atom feeds... a generic client would never find the feeds in the first place (because my seller element doesn't look anything like a Service document)... 
Any thoughts?

Have you looked at the threading extensions for Atom?

http://www.ietf.org/rfc/rfc4685.txt

I'm not a big fan of the service document.  As far as generic clients
go, I think they can infer the editability of a resource by the
presence of a link rel='edit' without needing to consult a service
document.  The response to a PUT request is what's authoritative, not
any sort of service document.  Allow headers work just as well to
provide a hint as to acceptable methods.

Where I do use a "service document" in an otherwise-Atom Protocol
system, I repurpose Google's XML sitemaps so I have a hierarchical
format, instead of using a root-level flat-file document to define a
hierarchy.

You can also have feeds of feeds in Atom, so I don't really understand
the disadvantage you're seeing.  I didn't propose Atom as the magical
solution to your problem, merely as a way forward.  Once you've
identified its actual shortcomings, you're free to abandon it, but it
will give you an awful lot of ideas on how to use link relations
properly.  See it through, though, since it provides a useful guideline
on how to arrange and link collections.

You can use standard link relations, even if you use your own
vocabulary as a resource model.  Better to use standard media types,
though.

-Eric

"piers_lawson" wrote:
>
> Mike, thank you for pointing out the draft inlining spec... it was
> interesting.
> 
> Jan, I started off the thread suggesting a format similar to the one
> that you put forward as one of my alternatives. I have been convinced
> by the idea that really the collection should not contain Account
> elements but some sort of link. The inlining idea is good in that it
> formalises combining a link with some data from the target
> resource.... at least it would be if the spec  had moved forward from
> being a draft ;-)
> 
> However, what I'm really pushing for is an example of publishing a
> feed (or even feeds) within other content, for example within the
> seller element from my last post. If I end up with something similar
> to my last post (i.e. a seller element that contains a feed element)
> I'm back to a custom vocabulary... at which point I can't see the
> advantage of using Atom feeds... a generic client would never find
> the feeds in the first place (because my seller element doesn't look
> anything like a Service document)... Any thoughts?
> 

Thanks for the quick response Eric. I'm certainly not dismissing Atom yet and I hope I'm learning a lot from it and this discussion. 

You mention a feed of feed approach... would that be a <feed> element that represents the parent resource, which then contained an <entry> for each "collection"? With the <entry> containing a link to the feed for that child collection (and possibly also containing an <inline> to provide a high level view of the child feed's content)?

I think what I'm missing is some good examples of using Atom outside of the basic scenario. So given a resource that has properties of its own, and perhaps is linked to at least one possibly two collections of other resources... how would you represent it? What XML would you envisage being returned when the parent is requested?

Thanks everyone for your time!

"piers_lawson" wrote:
> 
> You mention a feed of feed approach... would that be a <feed> element
> that represents the parent resource, which then contained an <entry>
> for each "collection"? With the <entry> containing a link to the feed
> for that child collection (and possibly also containing an <inline>
> to provide a high level view of the child feed's content)?
> 

Yes.  If the client wants to access a feed within a feed, it can follow
the link rel='related' instead of the link rel='self' of an entry in
the original feed.  The link rel='self' just points to the first entry
in the sub-collection.

This is the first I've heard of <inline>, so I can't answer as to that.

-Eric

Ok ya... very bad wording on my part. Not a violation of the spec -- more
just "disregard" for the spec.  So "SHOULD" is to be treated as: "you really
ought to unless you really know what you are doing and you have a good,
valid reason not to", not "this is a good idea that you might want to
consider". I find that most folks seem to be omitting a body in 201
responses for no reason other than they don't want to be bothered -- they
are treating POST as being exempt to HATEOAS, not even using the location
header to redirect or anything like that. It's just RPC with the procedure
call returning a URI that happens to be in the  location header. Pet peeve
of mine...

Anyways, I've find the use of "Location" in 201 and 3xx to be a bit strange.
On the one hand, you'd think that the intent of using it in 201 is to
redirect the client to the new resource while indicating that a new resource
has been created. But I've never been able to find a definitive statement on
whether 201 should result in a redirect. The only text that comes close is
in the text describing the location header itself:

   The Location response-header field is used to redirect the recipient
   to a location other than the Request-URI for completion of the
   request or identification of a new resource. For 201 (Created)
   responses, the Location is that of the new resource which was created
   by the request. For 3xx responses, the location SHOULD indicate the
   server's preferred URI for automatic redirection to the resource.

It's not clear to me if the use of the word 'redirect' in the first sentence
means an automatic request here or not -- you'd think it would be more
explicit in the description of 201 if it was. I read it as to be used for
automatic redirection in the 3xx case and identification of the new resource
in the 201 case. And AFAIK, no widely-used HTTP clients or browsers do
auto-redirect on 201

So if you don't redirect then this leaves the client in either the steady
state defined by the body or, if there was no body in the response, in the
same steady state it was in before the request (sort of like a 204
response).

That's my take anyways -- would love to know if anyone had authoritative
info on if 201 was supposed to redirect (and the body was means as a
"backup" as in the 3xx case).

Andrew

2010/2/2 Ant�nio Mota <amsmota@...>

> But SHOULD is not SHALL, is a recommendation not a imposition... So not
> having a body on a 201 could not be considered a violation of the spec...
> Wich indeed turns things more complicated in determining what a steady-state
> should be...
>
>
> _________________________________________________
>
> Melhores cumprimentos / Beir beannacht / Best regards
>
> Ant�nio Manuel dos Santos Mota
>
> http://card.ly/amsmota
> _________________________________________________
>
>
>
> 2010/2/2 wahbedahbe <andrew.wahbe@...>
>
>>
>>
>>
>>
>> --- In rest-discuss@yahoogroups.com <rest-discuss%40yahoogroups.com>, Jan
>> Algermissen <algermissen1971@...> wrote:
>> >
>> > When a client sends a POST request and receives a 201 Created...
>> >
>> > a) is the POST response body the steady state
>> >
>> > b) is it implied by HTTP spec that the client will do a GET on the
>> Location and is that the steady state?
>> >
>> > c) is this up to the media type that contained the link to the
>> POST-accepting resource?
>> >
>> >
>> >
>> > For other return codes I think this:
>> >
>> > 200 Ok - steady state is the POST response
>> > 202 Accepted - steady state is available at the link provided by the
>> body of the 202 response
>> > 303 See Other - steady state is available ta resource that the Location
>> points to
>> >
>> > Jan
>> >
>>
>> I think the HTTP spec is pretty clear that 201 responses SHOULD have a
>> body which constitutes your steady state.
>> Section 9.5:
>> If a resource has been created on the origin server, the response
>> SHOULD be 201 (Created) and contain an entity which describes the
>> status of the request and refers to the new resource, and a
>> Location header (see section 14.30)
>> Section 10.2.2:
>> The newly created resource can be referenced by the URI(s)
>> returned in the entity of the response, with the most specific URI
>> for the resource given by a Location header field. The response
>> SHOULD include an entity containing a list of resource
>> characteristics and location(s) from which the user or user agent
>> can choose the one most appropriate. The entity format is
>> specified by the media type given in the Content-Type header field.
>>
>> I've always considered the Location header in 201 responses as information
>> for intermediaries rather than the driver of application state. But I know
>> I'm in the minority on that: a lot of people don't even have a body in their
>> 201 responses (which to me is a violation of the spec).
>> Regards,
>>
>> Andrew
>>
>>  
>>
>
>


-- 
Andrew Wahbe

Andrew Wahbe wrote:
>
> Ok ya... very bad wording on my part. Not a violation of the spec --
> more just "disregard" for the spec.  So "SHOULD" is to be treated as:
> "you really ought to unless you really know what you are doing and
> you have a good, valid reason not to", not "this is a good idea that
> you might want to consider". (...)
>

The thing is, HTTP isn't constrained to being used on the Web.  So
there are plenty of things in there which, in the context of the Web,
become a "MUST" even though the spec says "SHOULD".  For example, the
use of registered media types.  If your context is intranet, then knock
yourself out disrespecting the SHOULD by creating new media types willy-
nilly.

If your context is the Web, then how is an intermediary to tell the
difference between one application/vnd.customers+xml and another?  Such
a collision is likely on the Web, so consider the use of registered
media types a MUST.  If your context is intranet, then g'head.  These
SHOULD instead of MUST situations in the spec aren't loopholes.

Off the Web, I send Content-Location with 201 responses instead of
Location, 'cuz it makes more sense to _me_ that way...  But, I haven't
read 2616bis lately (really need to quit putting that off, now), so I
can't really comment on the issue, beyond pointing out that the Web
turns a lot of HTTP's SHOULDs into MUSTs, for all intents and purposes.

-Eric

On Feb 3, 2010, at 5:56 AM, Andrew Wahbe wrote:

> 
> 
> Ok ya... very bad wording on my part. Not a violation of the spec -- more just "disregard" for the spec.  So "SHOULD" is to be treated as: "you really ought to unless you really know what you are doing and you have a good, valid reason not to", not "this is a good idea that you might want to consider". I find that most folks seem to be omitting a body in 201 responses for no reason other than they don't want to be bothered -- they are treating POST as being exempt to HATEOAS, not even using the location header to redirect or anything like that. It's just RPC with the procedure call returning a URI that happens to be in the  location header. Pet peeve of mine...
> 
> Anyways, I've find the use of "Location" in 201 and 3xx to be a bit strange. On the one hand, you'd think that the intent of using it in 201 is to redirect the client to the new resource while indicating that a new resource has been created. But I've never been able to find a definitive statement on whether 201 should result in a redirect. The only text that comes close is in the text describing the location header itself:
>    The Location response-header field is used to redirect the recipient
>    to a location other than the Request-URI for completion of the
>    request or identification of a new resource. For 201 (Created)
> 
>    responses, the Location is that of the new resource which was created
> 
>    by the request. For 3xx responses, the location SHOULD indicate the
>    server's preferred URI for automatic redirection to the resource.
> It's not clear to me if the use of the word 'redirect' in the first sentence means an automatic request here or not -- you'd think it would be more explicit in the description of 201 if it was. I read it as to be used for automatic redirection in the 3xx case and identification of the new resource in the 201 case. And AFAIK, no widely-used HTTP clients or browsers do auto-redirect on 201

I found this: http://www.w3.org/Protocols/HTTP/1.1/rfc2616bis/issues/#i61 (which suggests that the original intention was location of created resource OR redirect target).



> 
> So if you don't redirect then this leaves the client in either the steady state defined by the body or, if there was no body in the response, in the same steady state it was in before the request (sort of like a 204 response).

Yes. Interestingly, this means that the client's application state does not change although it made a request. But what if the client has this current state:

GET /book

<documentIndex>
  <chapter href="chapter1.xml"/>
  <chapter href="chapter2.xml"/>
  <appendix href="appendix1.xml"/>
  <chapters href="chapters/"/>
</documentIndex>

and then it does

DELETE /book/appendix1.xml

204 No Content

The client's state is now 'wrong' in the sense that the third link should be removed. Since the server cannot know what state the client was in before the DELETE request, it cannot really assist by sending the updated state.

Should the client take care of 'adjusting' the state itself?

On the contrary, if you did

POST /book/chapters/

<newCpater>

the server would usually say "Hey, this has updated some resource, look:"

303 See Other
Location: /book



Hmmm - so it is probably wise to do this then:

DELETE /book/appendix1.xml

303 See Other
Location: /book




> 
> That's my take anyways -- would love to know if anyone had authoritative info on if 201 was supposed to redirect (and the body was means as a "backup" as in the 3xx case).


See link above.

Jan

> 
> Andrew
> 
> 2010/2/2 Ant�nio Mota <amsmota@...>
> But SHOULD is not SHALL, is a recommendation not a imposition... So not having a body on a 201 could not be considered a violation of the spec... Wich indeed turns things more complicated in determining what a steady-state should be...
> 
> 
> _________________________________________________
> 
> Melhores cumprimentos / Beir beannacht / Best regards
> 
> Ant�nio Manuel dos Santos Mota
> 
> http://card.ly/amsmota
> _________________________________________________
> 
> 
> 
> 2010/2/2 wahbedahbe <andrew.wahbe@...>
>  
> 
> 
> 
> --- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
> >
> > When a client sends a POST request and receives a 201 Created...
> > 
> > a) is the POST response body the steady state
> > 
> > b) is it implied by HTTP spec that the client will do a GET on the Location and is that the steady state?
> > 
> > c) is this up to the media type that contained the link to the POST-accepting resource?
> > 
> > 
> > 
> > For other return codes I think this:
> > 
> > 200 Ok - steady state is the POST response
> > 202 Accepted - steady state is available at the link provided by the body of the 202 response
> > 303 See Other - steady state is available ta resource that the Location points to
> > 
> > Jan
> >
> 
> I think the HTTP spec is pretty clear that 201 responses SHOULD have a body which constitutes your steady state.
> Section 9.5:
> If a resource has been created on the origin server, the response
> SHOULD be 201 (Created) and contain an entity which describes the
> status of the request and refers to the new resource, and a 
> Location header (see section 14.30)
> Section 10.2.2:
> The newly created resource can be referenced by the URI(s)
> returned in the entity of the response, with the most specific URI
> for the resource given by a Location header field. The response
> SHOULD include an entity containing a list of resource
> characteristics and location(s) from which the user or user agent 
> can choose the one most appropriate. The entity format is 
> specified by the media type given in the Content-Type header field.
> 
> I've always considered the Location header in 201 responses as information for intermediaries rather than the driver of application state. But I know I'm in the minority on that: a lot of people don't even have a body in their 201 responses (which to me is a violation of the spec).
> Regards,
> 
> Andrew
> 
> 
> 
> 
> 
> -- 
> Andrew Wahbe
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...g
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

On Wed, Feb 3, 2010 at 2:29 AM, Jan Algermissen <algermissen1971@...>wrote:

> >
> > So if you don't redirect then this leaves the client in either the steady
> state defined by the body or, if there was no body in the response, in the
> same steady state it was in before the request (sort of like a 204
> response).
>
> Yes. Interestingly, this means that the client's application state does not
> change although it made a request. But what if the client has this current
> state:
>
> GET /book
>
> <documentIndex>
>  <chapter href="chapter1.xml"/>
>  <chapter href="chapter2.xml"/>
>  <appendix href="appendix1.xml"/>
>  <chapters href="chapters/"/>
> </documentIndex>
>
> and then it does
>
> DELETE /book/appendix1.xml
>
> 204 No Content
>
> The client's state is now 'wrong' in the sense that the third link should
> be removed. Since the server cannot know what state the client was in before
> the DELETE request, it cannot really assist by sending the updated state.
>
> Should the client take care of 'adjusting' the state itself?
>
> On the contrary, if you did
>
> POST /book/chapters/
>
> <newCpater>
>
> the server would usually say "Hey, this has updated some resource, look:"
>
> 303 See Other
> Location: /book
>
>
>
> Hmmm - so it is probably wise to do this then:
>
> DELETE /book/appendix1.xml
>
> 303 See Other
> Location: /book
>
>
>
 Good point. One thing about PUT and DELETE is that, other than Atom, there
aren't a lot (any?) good examples of how to use them in hypermedia. AFAIK,
HTML5 is just saying to add them as an option on <form> which is a bit silly
-- there doesn't seem to be any sense in a single hypertext construct being
used for GET, POST, PUT and DELETE. The use cases and application flows for
the different methods are just so different.

Let's consider Atom as an example here (as that's all we've got). If your
client is reading a feed and decides to delete an entry and gets a 204 back,
does the client have to GET the feed again before it can take any other
actions on the feed? Or can it assume that the DELETE operation had the
consequences outlined by HTTP, AtomPub and the edit relation and make an
assumption about the current state of the feed?

In other words: maybe 204 doesn't mean "the steady state hasn't changed" but
rather "the steady state has been adjusted as defined by the media type and
the method"?

Regards,

Andrew

http://www.jfokus.se/jfokus/preso/jf-10_DomainDrivenRESTWeb-Services.pdf

thanks for all discussions here... every opinion influenced my under
progress work ..

Now I am designing and implementing the HATEOAS workflow engine....
let's see.....

* there are some terminology and conceptual abuse in my slides, but
live I commented out about that (like why application/xml is not
enough for rest, etc)...

-- 
------------------------------------------
   Felipe Ga�cho
   10+ Java Programmer
   CEJUG Senior Advisor

This wound up a long post, so I'm going to start by pre-stating that
HTTP is an application protocol, and by prepeating my summary as thesis:

Application steady states are derived from HTTP messaging (think of a
browser diplaying a default 'broken image' icon, a different steady-
state than one where the image was retrieved and rendered) separately
from the state (and media type) of the resource that provided the
container representation.

Andrew Wahbe wrote:
>
> Good point. One thing about PUT and DELETE is that, other than Atom,
> there aren't a lot (any?) good examples of how to use them in
> hypermedia. AFAIK, HTML5 is just saying to add them as an option on
> <form> which is a bit silly
>

Last I checked, adding Xforms to HTML 5 was still under active
consideration.  I don't consider Atom a good example of using PUT and
DELETE in hypermedia, because the hypermedia isn't actually instructing
the client what to do.  I have mentioned my Xforms Atom Protocol
client, coming soon to a demo near you...

My initial posting of the demo won't include a nifty Xforms interface,
though.  The pragmatic reason for distilling out a static demo from my
ongoing project, is to fully explore the notion of Xforms client
implementation -- Xforms relies on XHTML or SVG as a host language, so
it's a matter of client capability that isn't exposed in headers,
meaning you can't conneg around the problem, so I'm kinda stuck...

The demo will also (eventually) have a sandbox for publishing text/plain
files (until it gets spammed, anyway) that y'all can play with, which
allows for PUT and DELETE.  Obviously, text/plain isn't a media type
which describes PUT and DELETE, but the interface is Xforms, which adds
support for those methods into the host-language media type -- the
media types of the host language and the target don't matter to my
sandbox API, so long as Xforms is allowed by the host language...

The directory contents will be modeled as XBEL, using application/xbel
+xml, and served (like the rest of the demo) using client-side XSLT to
turn that into XHTML + Xforms.  The sandbox API, unlike Atom Protocol,
is RESTful and does it without minting any media (sub)types, by using an
existing media type already defined for collections of URIs of any media
type...

If logged in using HTTP Digest, the username is used as the port 80
process ID (group 'user' not 'www').  File creation is handled via POST
to the collection, as with Atom Protocol.  Users may only DELETE files
they have created, but may edit (PUT) files created by others, based on
the standard UNIX file and directory permissions already constraining
the behavior of the httpd.

The "sandbox API" is what I've been using for years to update .xsl, .css
and .js files on my previous demos (without the newly-added hypertext
constraint).  If I need to close the sandbox, I just 'chmod -w sandbox',
or make the server 410 with '-r' (at directory or file level).  Allowing
curl to PUT and DELETE is easy on an httpd, making it REST requires a
couple of extra steps, though.  It's pretty cool, but I promise to stop
fiddling with it and post my demo without...

You can, of course, utilize the sandbox without the Xforms interface
(this 'paleowiki' is even fun to use with curl).  But, in terms of
"learning the API" you can see it plain as day in the server-generated
hypertext application that self-documents it, and by introspecting
response codes with a protocol analyzer.  So g'head (soon) and write a
quickie sandbox API client using libcurl, or just play with it using
curl.  I don't care if you don't follow my provided hypertext, just
that I've met REST's burden of providing it, so you can figure out how
to use curl by using 'view source'.

>
> -- there doesn't seem to be any sense in a single hypertext construct
> being used for GET, POST, PUT and DELETE. The use cases and
> application flows for the different methods are just so different.
> 

I agree; it's the immediate drawback I notice in:

http://www.w3.org/2007/03/html-forms/

Which I'm going to give a whirl, anyway.  I prefer the raw Xforms MVC
design pattern.  I have nothing against MVC per se, only its all-too-
common usage on the Web in systems which break the identification of
resources constraint.  Putting MVC on the client makes it a RESTful
design pattern.  The 'XRX' design pattern mates an Xforms frontend to
an Xquery backend; this design pattern may easily be implemented as a
decoupled REST system.

I can't get enough of that buzz I get writing Xforms applications for
RESTful systems -- the ability to rapidly prototype Web systems for
visualization and analysis, without using Javascript, blows me away.  If
only I could figure out how to serve my Xforms applications to generic
clients, say by having Xforms included within HTML 5, I'd be thrilled...

>
> Let's consider Atom as an example here (as that's all we've got). If
> your client is reading a feed and decides to delete an entry and gets
> a 204 back, does the client have to GET the feed again before it can
> take any other actions on the feed? Or can it assume that the DELETE
> operation had the consequences outlined by HTTP, AtomPub and the edit
> relation and make an assumption about the current state of the feed?
> 

Yes (sorta), and no.  A client can't assume a 2xx response to mean
'success' because of 202.  If the server has no intention of performing
the DELETE, then it should use a 4xx response.  OTOH, a server isn't
beholden to its own 2xx response to a DELETE, so "caveat client"
applies.  This goes for any media type, not just Atom, btw.

The server's response to a DELETE request is only the server's response
to the request (a shadow in Plato's cave).  The effect on the resource
(the true form) can only be determined via subsequent request.  Most
servers will change their response to 404, when the correct response is
usually a 410.  But, even that depends on the context of the DELETE
request...

What if the DELETE request had a Link header whose link relation and
content describe the proper forwarding for the resource?  If the
deleted resource has been combined with another, then a 307 redirect is
called for.  However, if the resource has been moved to a new location,
the response would be a 301 redirect.  Even if the client has no
control over this, the response code to the DELETE request itself, isn't
authoritative of much.

>
> In other words: maybe 204 doesn't mean "the steady state hasn't
> changed" but rather "the steady state has been adjusted as defined by
> the media type and the method"?
> 

It means neither.  It only informs the client that the DELETE request
didn't result in an error.  Only the responses to GET, HEAD or OPTIONS
requests tell you anything about resource state.  Any of these requests
made subsequent to a DELETE request will give a response code
indicating the state of the resource -- not found, gone, moved or
(perhaps) merged, etc.  (Or, in the case of a collection feed, perhaps
all members were deleted, or just the collection, or both.)

REST "application state" is held entirely on the client.  A REST system
has literally infinite "applications," defined as "what the user is
trying to do."  The application presents the user with a representation
of resource state -- that's the first "steady state," when a form with a
delete button finishes loading and styling.  That delete form allows
users to construct their own choice for the next state transition.

(Other possible state transition selections I'll ignore include, but
are not limited to:  menu links, mailto links, links to help with the
form, etc. which may also appear as part of the form's steady-state.)

When a user hits the delete button, a DELETE request is sent to the
identified resource.  Now, all heck breaks loose!  We haven't a clue as
to the result of this action beyond "request accepted" or "request
rejected," which have nothing to do with resource state -- but
everything to do with *application* state.

What happens when the response is 4xx?  There's no rule that says you
have to treat that 4xx response as the next application state (even
though you may do so).  If you do, there's no reason the body of the
4xx response can't look identical to the last steady-state, although
you may want to add some text (or styling) indicating the failure.  You
aren't limited to presenting your application within 200 responses.

If you don't want to load a new page, then Xforms can catch the response
code and restyle the page accordingly.  For example, if the response
was 4xx, color the filename text red, gray it out, and make it not
selectable.  There -- the application just transitioned to a new steady-
state without following any links (loading a new page).  (The sandbox
API returns 202 Accepted to DELETE, does chmod -r and removes the file
from the XBEL index, causing a 410 response to subsequent requests --
who says my server has to allow you to delete your death threats...? ;-)

Likewise, if the response is 2xx, Xforms can turn right around and make
a HEAD request to the allegedly-deleted resource.  If the response to
that is 4xx, the filename text is removed from the delete form's select
box (the sandbox API just reloads the XBEL file regardless of response).
There -- the application transitioned to a new steady-state without
following any links, again.  HTTP is an application messaging protocol.

The URI which responded with the delete form, has that delete form as
its resource state.  But, the client's application state varies based
on the state of each resource in the directory it represents in its
select box as a list of filenames (or the state of a linked XBEL-
represented index resource, in the sandbox API case -- the XBEL document
is the Xforms 'Model', so refreshing the model shows the outcome of the
DELETE request, which will be 304 on failure due to matching Etag).

So the state of such a delete application transitions from one steady-
state to another based on the user selecting a filename and clicking
the delete button -- regardless of whether your delete form is updating
dynamically, or you are using it as a representation of the success and
failure states expressed in response to the DELETE (by following the
link, i.e. loading a new 4xx response page, dereferencing the deleted
URL, whatevah), or media type used (I've given a general idea on how
this is done, plus specifics of how it's done in my forthcoming sandbox
API, without mentioning Atom).

About the only REST no-no with a 204 response, is to present the user
with that response as the next application state -- a blank page.  So
the client needs to have some logic, i.e. make a HEAD request and
dynamically restyle, or make a GET request and present the user with a
"success" application state wrapped in a 4xx response (which breaks no
REST constraints -- resource state and application state aren't the
same thing).

In a nut, this behavior is out-of-scope to media type, it's all about
HTTP as application (not transport) protocol.  Application steady
states are derived from HTTP messaging (think of a browser diplaying a
default 'broken image' icon, a different steady-state than one where
the image was retrieved and rendered) separately from the state of the
resource that provided the container representation.

</ramble_on>

Watching Pagey "Ramble On" on my "It Might Get Loud" DVD too much,
Eric

Thanks Eric,

Could you post a small sample showing what you mean exactly. So a feed that contains one (or even better two feeds)... and for the parent feed and the child feeds they contain some additional data beyond the standard fields supportted by Atom. I think an example would really solidify it in my mind.

Thank you for your input so far!

OK, it's rough around the edges yet, but it's time I posted it.  There
are a few ways in.  If you're interested in the httpd project, start
here, any browser will do:

http://charger.bisonsystems.net/
http://charger-admin.bisonsystems.net/

Or, you can jump into the project directly, but compatibility is
currently limited to Firefox:

http://charger.bisonsystems.net/xmltest/index.xht

Yeah, there's a button to push.  Sorry, I'm working on Xforms capability
in an unobtrusive fashion, but development of same is required to be
obtrusive.

Normally, I restrict all the internals stuff to localhost access, but
for this demo I've created the charger-admin alias.  Don't worry, the
whole thing is read-only, so you can't do any damage.  (I hope...  :-)

The purpose is to demo a whole buncha stuff.  The only links that work
(apart from the directory browser) are the ones in body content, and
the 'View' menu (the button for which takes you back into the directory
browser, btw), but the variants are under construction so there's
nothing to see there at this time.

Drilling down to individual posts, comment threads, and standalone
comments does work.  And, all from one XSLT stylesheet.  That's the
part where the application logic and XHTML template are cached on the
client, and based entirely on standard elements and link relations.
The applicability of this, of course, goes far beyond the demo's nature
as a weblog.

Sandbox API is next, after the /date service is finished (a simple REST
service to transform ISO 8601 date strings into human-readable form).

All further notes are there in the project.  Q&A taken here, on-topic
to the RESTful nature of the design (and proposed design, as described
by the Accept and Allow headers).  I haven't figured out what I want to
do with OPTIONS on this project, yet.

-Eric

Hello Eric,

Feedback coming in... just a few clicking around (safari) and noticed
content "negotiation" through URI template:
http://charger.bisonsystems.net/xmltest/2006/aug/09/11.axml (also a 404
here)

Regards

Guilherme Silveira
Caelum | Ensino e Inova��o
http://www.caelum.com.br/


On Sat, Feb 6, 2010 at 8:33 PM, Eric J. Bowman <eric@...>wrote:

>
>
> OK, it's rough around the edges yet, but it's time I posted it. There
> are a few ways in. If you're interested in the httpd project, start
> here, any browser will do:
>
> http://charger.bisonsystems.net/
> http://charger-admin.bisonsystems.net/
>
> Or, you can jump into the project directly, but compatibility is
> currently limited to Firefox:
>
> http://charger.bisonsystems.net/xmltest/index.xht
>
> Yeah, there's a button to push. Sorry, I'm working on Xforms capability
> in an unobtrusive fashion, but development of same is required to be
> obtrusive.
>
> Normally, I restrict all the internals stuff to localhost access, but
> for this demo I've created the charger-admin alias. Don't worry, the
> whole thing is read-only, so you can't do any damage. (I hope... :-)
>
> The purpose is to demo a whole buncha stuff. The only links that work
> (apart from the directory browser) are the ones in body content, and
> the 'View' menu (the button for which takes you back into the directory
> browser, btw), but the variants are under construction so there's
> nothing to see there at this time.
>
> Drilling down to individual posts, comment threads, and standalone
> comments does work. And, all from one XSLT stylesheet. That's the
> part where the application logic and XHTML template are cached on the
> client, and based entirely on standard elements and link relations.
> The applicability of this, of course, goes far beyond the demo's nature
> as a weblog.
>
> Sandbox API is next, after the /date service is finished (a simple REST
> service to transform ISO 8601 date strings into human-readable form).
>
> All further notes are there in the project. Q&A taken here, on-topic
> to the RESTful nature of the design (and proposed design, as described
> by the Accept and Allow headers). I haven't figured out what I want to
> do with OPTIONS on this project, yet.
>
> -Eric
>  
>

> 
> Feedback coming in... just a few clicking around (safari) and noticed
> content "negotiation" through URI template:
> http://charger.bisonsystems.net/xmltest/2006/aug/09/11.axml (also a
> 404 here)
> 

Yeah, that stuff isn't built yet.  I had to get creative with filename
extensions, but that's a contrivance of the demo.

-Eric

The default httpd response is the domain parking page, which you can
see in action here:

http://way.groo.vi/

Nanoweb has lots of cool stuff that I'm trying not to break, and some
solid ideas for httpd implementation, including an .nwaccess format
that's bass-ackwards from .htaccess but which I prefer.

-Eric

Hey all,

Volume 2 of This week in REST is up on the REST wiki -
http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Feb_1_2010
and the blog - http://bit.ly/almkw1

For contributing links this week visit
http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Feb_8_2010

Enjoy :)

Cheers,
Ivan

"piers_lawson" wrote:
> 
> Could you post a small sample showing what you mean exactly. So a
> feed that contains one (or even better two feeds)... and for the
> parent feed and the child feeds they contain some additional data
> beyond the standard fields supportted by Atom. I think an example
> would really solidify it in my mind.
> 

I'm working on your example.  The demo I posted shows what I'm talking
about, but I haven't worked the rest of my solution into the demo yet.
When I have, I'll bump here.  I'm almost finished (I think) making the
XSLT also function in Opera (using a holistic approach to the cross-
browser XSLT problem, rather than using @mode and an engine test, i.e.
making some code specific to Mozilla's Transformiix processor or Opera's
libxslt).

After I've made the XSLT work with WebKit, I'll work those other tricks
up my sleeve for dealing with collections into the demo.  Then I'll make
the XSLT work with IE, so I can get back to my original problem, which
is dealing with Xforms.  IE has a couple of nice Xforms extensions
available.

The result of this work, for me, will be a development style based on
the union of subsets of XSLT 1.0, EXSLT and Xforms that works on the
Web.  And, a coding style (which can be validated using RELAX NG +
Schematron) for hitting that cross-browser sweet spot, which results in
code that also works for server-side transformation (if nothing else
works, libxslt can be used on the server).

Anyway, I ought to be able to provide an interesting collection example
for you later this week.

-Eric

Am 01.02.10 19:17, schrieb mike amundsen:

> *** REQUEST
> POST /prove-it HTTP/1.1
> Host: www.example.org
> Content-Type: application/x-www-form-urlencoded
> User-Agent: common-browser/1.0
> 
> captcha-image=http%3A%2F%2Fwww.example.org%2Fcaptcha-images%2Fa1s2d3f4g5.png&user-name=Mike&captcha-animal=kitten
> 
> *** RESPONSE
> HTTP/1.1 400 Bad Request
> Date: ...
> Server: smart-server/9.0
> ...
> Content-Type: text/html
> Content-Length: nnn
> 
> ...
> <p class="error">Sorry, that was not a photo of a kitten. You must not
> be human.</p>


Use used 400 bad request as response wich make sense. I used 412
precondition failed until now an I wonder if there is any reason to
prefer either one.

Philipp Meier

All,

 

as there's going to be a session on OpenRasta at the Mix conference, I'm thinking of organizing a small get-together over there for all ReSTafarians.

 

Anyone around between 14th and 18th of March?

 

Seb
 		 	   		  
_________________________________________________________________
Tell us your greatest, weirdest and funniest Hotmail stories
http://clk.atdmt.com/UKM/go/195013117/direct/01/

Hi Seb,

I'll be there again...

Dave Evans

-----Original Message-----
From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com] On
Behalf Of Sebastien Lambla
Sent: 11 February 2010 11:52
To: rest-discuss@yahoogroups.com
Subject: [rest-discuss] Las Vegas for Mix10, any restafarians around?



All,
 
as there's going to be a session on OpenRasta at the Mix conference, I'm
thinking of organizing a small get-together over there for all ReSTafarians.
 
Anyone around between 14th and 18th of March?
 
Seb


________________________________

We want to hear all your funny, exciting and crazy Hotmail stories. Tell us
now <http://clk.atdmt.com/UKM/go/195013117/direct/01/>  

Volume 3 of This week in REST is up on the REST wiki -
http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Feb_8_2010
and the blog - http://bit.ly/9S2HM3

For contributing links this week visit
http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Feb_15_2010

How are you guys liking TWIR so far? Any suggestions on making it better?

Thanks,
Ivan

Which is the best way to deal with content negotiation?
I mean that the server could detect and handle the content
type requested by the client

As far I know I could use the following mechanisms

� Using the ACCEPT or CONTENT_TYPE HTTP headers
� Using a format request parameter, clients can request a specific content type, as in  http:/something/resource?format=xml
� Using the file extension in the URI, as in 
http:/something/resource.xml.


Thanks in advance.

One of these doesn't belong:

> 
> � Using the ACCEPT or CONTENT_TYPE HTTP headers
> � Using a format request parameter, clients can request a specific
> content type, as in  http:/something/resource?format=xml � Using the
> file extension in the URI, as in http:/something/resource.xml.
> 

The middle one.  You have a negotiated resource:

http://something/resource

The resource analyzes the ACCEPT header of an incoming request, and
chooses the appropriate variant, let's say it negotiates between:

http://something/resource.xml
http://something/resource.svg

Or something.  The server responds with the correct Content-Type for
the variant it returns, and includes the URL in a Content-Location
header.  Don't forget to Vary: Accept.

-Eric

On Mon, Feb 15, 2010 at 7:57 AM, javier <vrhj2000@...> wrote:
> Which is the best way to deal with content negotiation?
> I mean that the server could detect and handle the content
> type requested by the client
>
> As far I know I could use the following mechanisms
>
> � Using the ACCEPT or CONTENT_TYPE HTTP headers
> � Using a format request parameter, clients can request a specific content type, as in �http:/something/resource?format=xml
> � Using the file extension in the URI, as in
> http:/something/resource.xml.

There's also the use of the Link header + "alternate" relation in a
response, permitting the server to inform the client what
representations it has available.  I think it's safe to say that
there's now consensus in the HTTP community that this is the most
general solution.

Mark.

On Feb 16, 2010, at 3:43 PM, Mark Baker wrote:

> On Mon, Feb 15, 2010 at 7:57 AM, javier <vrhj2000@...> wrote:
>> Which is the best way to deal with content negotiation?
>> I mean that the server could detect and handle the content
>> type requested by the client
>> 
>> As far I know I could use the following mechanisms
>> 
>> � Using the ACCEPT or CONTENT_TYPE HTTP headers
>> � Using a format request parameter, clients can request a specific content type, as in  http:/something/resource?format=xml
>> � Using the file extension in the URI, as in
>> http:/something/resource.xml.
> 
> There's also the use of the Link header + "alternate" relation in a
> response, permitting the server to inform the client what
> representations it has available.  I think it's safe to say that
> there's now consensus in the HTTP community that this is the most
> general solution.

I'd like to add a pointer to http://tools.ietf.org/html/rfc2295 , especially the Alternates header: http://tools.ietf.org/html/rfc2295#section-8.3

Jan


> 
> Mark.
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

I'm working on an HTTP service-oriented system.  I'm trying to figure out
how to communicate validation exceptions from the server to the client.  For
example, if I have a resource that uses the URI template: /foo/{id}, where
{id} has to be a number.  Is the right status in those cases 400/Bad
Request?  How about for a an incorrectly formatted date query parameter?

Does anyone have further advice about contents of a body format (some form
of json/xml) that would embody the details of the invalid parameters?

This type of validation is second nature to web-based form entry and HTML
based frameworks, but doing it data-oriented is new (at least to me).  Are
there common ways to represent validation errors?


Thanks

-Solomon Duskis

Given that the creation of APIs that ignore the hypermedia constraint is undeniably an ongoing activity wouldn't it be nice to give those a name in order to differentiate them from RESTful APIs?

I think that it can in various circumstances be argued to be to have HTTP based APIs that define some URI layout and maybe only use generic media types. It is certainly more useful than doing the same API with RMI, SOAP or CORBA.

However, given there is no name for them, they simple become 'REST-APIs' which obfuscates the fact that systems using those APIs will *not* have the properties induced by REST.

If we name them, differentiation between the two becomes a lot easier.


What I lack is a compelling name that sounds cool enough so API owners can still be proud even if they are not (yet) in the REST-Olymp of things :-) ?

Any ideas?


HTTP-base APIs
Fixed-URI-APIs

Both *not* cool....

Jan



-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

On Feb 16, 2010, at 9:40 PM, Solomon Duskis wrote:

> 
> 
> I'm working on an HTTP service-oriented system.  I'm trying to figure out how to communicate validation exceptions from the server to the client.  For example, if I have a resource that uses the URI template: /foo/{id}, where {id} has to be a number.  Is the right status in those cases 400/Bad Request?  How about for a an incorrectly formatted date query parameter?

I used 422 Unprocessable Entity for that (but on a form data POST request)

What about aa 404 with an HTML body explainig the cause?

> 
> Does anyone have further advice about contents of a body format (some form of json/xml) that would embody the details of the invalid parameters?
> 

I like to use HTML with a well-known micro format that enables programs to parse out aspects of the messge.


> This type of validation is second nature to web-based form entry and HTML based frameworks, but doing it data-oriented is new (at least to me).  Are there common ways to represent validation errors?
> 


400 Bad Request syntactical error
409 Confilct  (logical error [this is bending the meaning a little]
415 Unsupported Media Type (server does not know request body type)
422 Unprocessable Entity semantic error

Jan

> 
> Thanks
> 
> -Solomon Duskis
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Hi Jan,

Thanks for the response!  There are quite a few WebDAV status codes that I
didn't know about.

Regarding the following:


> <snip>
>


> >
> > Does anyone have further advice about contents of a body format (some
> form of json/xml) that would embody the details of the invalid parameters?
> >
>
> I like to use HTML with a well-known micro format that enables programs to
> parse out aspects of the messge.


Do you have examples of such a well-known micro format?

-Solomon

On Feb 16, 2010, at 10:04 PM, Solomon Duskis wrote:

> Hi Jan,
> 
> Thanks for the response!  There are quite a few WebDAV status codes that I didn't know about.  
> 
> Regarding the following:
>  
> <snip>
>  
> >
> > Does anyone have further advice about contents of a body format (some form of json/xml) that would embody the details of the invalid parameters?
> >
> 
> I like to use HTML with a well-known micro format that enables programs to parse out aspects of the messge.
> 
> Do you have examples of such a well-known micro format?

You could say that you constrain the HTML to include

<p class="error"></p>
<p class="suggested-fix"></p>
<p class="stack-trace"></p>

nothing fancy really, just something to make sure machine can do a little bit with it instead of dump it right into the log :-)


Jan

> 
> -Solomon

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

I include a definition of an error message in all the media-type formats I
use. This error item could appear within the body of any response from the
server:

XML
<error>
  <code />
  <message />
  <details />
</error>

JSON
{'error':{'code':'','message':'','details':''}}

XHTML (used w/ Atom, too)
<div class="error">
  <span class="code"></span>
  <span class="message"></span>
  <span class="details"></span>
</div>

mca
http://amundsen.com/blog/



On Tue, Feb 16, 2010 at 16:04, Solomon Duskis <sduskis@...> wrote:

>
>
> Hi Jan,
>
> Thanks for the response!  There are quite a few WebDAV status codes that I
> didn't know about.
>
> Regarding the following:
>
>
>> <snip>
>>
>
>
>>  >
>> > Does anyone have further advice about contents of a body format (some
>> form of json/xml) that would embody the details of the invalid parameters?
>> >
>>
>> I like to use HTML with a well-known micro format that enables programs to
>> parse out aspects of the messge.
>
>
> Do you have examples of such a well-known micro format?
>
> -Solomon
>
>
> 

A while back I put together the following set of "not quite REST" style definitions for a discussion I was having with some colleagues:

RPC
---
- HTTP-based RPC (SOAP or POX over HTTP etc.)
- only meets the client-server constraint

Unlinked Resource Oriented
--------------------------
- has well-defined resources at distinct URIs and uses HTTP methods properly. But representations are just serialized "data" with no links
- meets client-server, layered system, caching, stateless (usually -- some stray here via cookies etc.), identification of resources, manipulation of resources through representations
- partially meets self-descriptive messages in that HTTP meta-data is used properly but a non-standard media-type or "generic" media type (XML, JSON) or otherwise "anemic" format is used

Resource Oriented
-----------------
Like Unlinked Resource Oriented but with links in the data.
- this is tricky on the constraints met. Meets the same constraints as above; self-descriptive messages still not met because of non-standard or generic format. Arguably only partially meets HATEOAS even though there are links.

The distinction between "Resource Oriented" and REST is subtle. This is basically many of the APIs out there that miss the mark in media type design. Yes there are links, and so the client is still decoupled from the URI layout, but the client is bound to details of the service in other ways Roy outlines in his "REST APIs must by hypertext-driven" blog posting. The result is that you still have clients that are still very coupled to the service as the media type does not enable the client to be driven without other out-of-band info. In short, you can't just throw URIs into arbitrary JSON and get hypermedia (though that is what you often see in this style).

Anyways, that was what I came up with. It's not quite 3 out of 4 of the interface constraints style you propose -- I actually can't say that I see that too often. I would define that as an API where the representation is in a well defined, standard format that is not hypermedia -- what is a good example of this kind of format (that is used in APIs)?
Regards,

Andrew

--- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
>
> Given that the creation of APIs that ignore the hypermedia constraint is undeniably an ongoing activity wouldn't it be nice to give those a name in order to differentiate them from RESTful APIs?
> 
> I think that it can in various circumstances be argued to be to have HTTP based APIs that define some URI layout and maybe only use generic media types. It is certainly more useful than doing the same API with RMI, SOAP or CORBA.
> 
> However, given there is no name for them, they simple become 'REST-APIs' which obfuscates the fact that systems using those APIs will *not* have the properties induced by REST.
> 
> If we name them, differentiation between the two becomes a lot easier.
> 
> 
> What I lack is a compelling name that sounds cool enough so API owners can still be proud even if they are not (yet) in the REST-Olymp of things :-) ?
> 
> Any ideas?
> 
> 
> HTTP-base APIs
> Fixed-URI-APIs
> 
> Both *not* cool....
> 
> Jan
> 
> 
> 
> -----------------------------------
>  Jan Algermissen, Consultant
>  NORD Software Consulting
> 
>  Mail: algermissen@...
>  Blog: http://www.nordsc.com/blog/
>  Work: http://www.nordsc.com/
> -----------------------------------
>

On Feb 16, 2010, at 10:37 PM, wahbedahbe wrote:

> 
> Resource Oriented
> -----------------


That's actually quite good I think.


Thoug 'resource orientation' nomadays implies REST :-) Oh well...



Jan

On Feb 16, 2010, at 7:24 AM, Eric J. Bowman wrote:

> One of these doesn't belong:
> 
> > 
> > � Using the ACCEPT or CONTENT_TYPE HTTP headers
> > � Using a format request parameter, clients can request a specific
> > content type, as in http:/something/resource?format=xml
> > � Using the file extension in the URI, as in http:/something/resource.xml.
> > 
> 
> The middle one. 

Interesting. I claim there's no difference at all between options two and three, as at least from a REST perspective there's no difference between a query parameter and a file extension.

I wonder why you'd disagree?

Stefan
--
Stefan Tilkov, http://www.innoq.com/blog/st/

On Feb 16, 2010, at 9:40 PM, Solomon Duskis wrote:

> I'm working on an HTTP service-oriented system.  I'm trying to figure out how to communicate validation exceptions from the server to the client.  For example, if I have a resource that uses the URI template: /foo/{id}, where {id} has to be a number.  Is the right status in those cases 400/Bad Request?  How about for a an incorrectly formatted date query parameter?
> 
> 
> Does anyone have further advice about contents of a body format (some form of json/xml) that would embody the details of the invalid parameters?
> 

The second time today I'm writing something to this effect: AFAICT from your description, a resource /foo/123 exists, a resource /foo/abc doesn't � that sounds like a clear 404 to me. As Jan points out, some descriptive text in HTML with or without a microformat seems reasonable.

Stefan
--
Stefan Tilkov, http://www.innoq.com/blog/st/

Recess uses 409 for validation errors.  I think it fits well.
409 Conflict

The request could not be completed due to a conflict with the current state
of the resource. This code is only allowed in situations where it is
expected that the user might be able to resolve the conflict and resubmit
the request. The response body SHOULD include enough information for the
user to recognize the source of the conflict. Ideally, the response entity
would include enough information for the user or user agent to fix the
problem; however, that might not be possible and is not required.
[...]

- Kev


On Tue, Feb 16, 2010 at 12:40 PM, Solomon Duskis <sduskis@...> wrote:

>
>
> I'm working on an HTTP service-oriented system.  I'm trying to figure out
> how to communicate validation exceptions from the server to the client.  For
> example, if I have a resource that uses the URI template: /foo/{id}, where
> {id} has to be a number.  Is the right status in those cases 400/Bad
> Request?  How about for a an incorrectly formatted date query parameter?
>
> Does anyone have further advice about contents of a body format (some form
> of json/xml) that would embody the details of the invalid parameters?
>
> This type of validation is second nature to web-based form entry and HTML
> based frameworks, but doing it data-oriented is new (at least to me).  Are
> there common ways to represent validation errors?
>
>
> Thanks
>
> -Solomon Duskis
>  
>

Rigid?  Static?  Fixed?

- Kev


On Tue, Feb 16, 2010 at 12:39 PM, Jan Algermissen
<algermissen1971@...>wrote:

>
>
> Given that the creation of APIs that ignore the hypermedia constraint is
> undeniably an ongoing activity wouldn't it be nice to give those a name in
> order to differentiate them from RESTful APIs?
>
> I think that it can in various circumstances be argued to be to have HTTP
> based APIs that define some URI layout and maybe only use generic media
> types. It is certainly more useful than doing the same API with RMI, SOAP or
> CORBA.
>
> However, given there is no name for them, they simple become 'REST-APIs'
> which obfuscates the fact that systems using those APIs will *not* have the
> properties induced by REST.
>
> If we name them, differentiation between the two becomes a lot easier.
>
> What I lack is a compelling name that sounds cool enough so API owners can
> still be proud even if they are not (yet) in the REST-Olymp of things :-) ?
>
> Any ideas?
>
> HTTP-base APIs
> Fixed-URI-APIs
>
> Both *not* cool....
>
> Jan
>
> -----------------------------------
> Jan Algermissen, Consultant
> NORD Software Consulting
>
> Mail: algermissen@... <algermissen%40acm.org>
> Blog: http://www.nordsc.com/blog/
> Work: http://www.nordsc.com/
> -----------------------------------
>
>  
>

On Tue, Feb 16, 2010 at 12:53 PM, Kev Burns <kevburnsjr@...> wrote:

> Recess uses 409 for validation errors.� I think it fits well.
>
> 409 Conflict
>
> The request could not be completed due to a conflict with the current state of the
> resource. This code is only allowed in situations where it is expected that the
> user might be able to resolve the conflict and resubmit the request. The response
> body SHOULD include enough information for the user to recognize the source
> of the conflict. Ideally, the response entity would include enough information for
> the user or user agent to fix the problem; however, that might not be possible
> and is not required.

That sounds like a good plan overall, but for this specific instance,
I don't think it's valid.

In this case, there is no resource state to be conflicted with, as the
actual resource identity is the problem.

Having an explanation in the body of a 404 is a better choice for this
specific case.

Regards,

Will Hartung
(willh@...)

I call them POD services, for Plain Old Data.
 


To: algermissen1971@mac.com
CC: rest-discuss@yahoogroups.com
From: kevburnsjr@...
Date: Tue, 16 Feb 2010 12:55:47 -0800
Subject: Re: [rest-discuss] A Name for "3 out of 4 REST constraints" APIs?







Rigid?  Static?  Fixed?
- Kev



On Tue, Feb 16, 2010 at 12:39 PM, Jan Algermissen <algermissen1971@...> wrote:


  



Given that the creation of APIs that ignore the hypermedia constraint is undeniably an ongoing activity wouldn't it be nice to give those a name in order to differentiate them from RESTful APIs?

I think that it can in various circumstances be argued to be to have HTTP based APIs that define some URI layout and maybe only use generic media types. It is certainly more useful than doing the same API with RMI, SOAP or CORBA.

However, given there is no name for them, they simple become 'REST-APIs' which obfuscates the fact that systems using those APIs will *not* have the properties induced by REST.

If we name them, differentiation between the two becomes a lot easier.

What I lack is a compelling name that sounds cool enough so API owners can still be proud even if they are not (yet) in the REST-Olymp of things :-) ?

Any ideas?

HTTP-base APIs
Fixed-URI-APIs

Both *not* cool....

Jan

-----------------------------------
Jan Algermissen, Consultant
NORD Software Consulting

Mail: algermissen@...
Blog: http://www.nordsc.com/blog/
Work: http://www.nordsc.com/
-----------------------------------







 		 	   		  
_________________________________________________________________
Do you have a story that started on Hotmail? Tell us now
http://clk.atdmt.com/UKM/go/195013117/direct/01/

Ah, the old Addressable Resources Sans Engine Of Application State conundrum.

No, nothing comes to mind.

ian

--- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
>
> Given that the creation of APIs that ignore the hypermedia constraint is undeniably an ongoing activity wouldn't it be nice to give those a name in order to differentiate them from RESTful APIs?
> 
> I think that it can in various circumstances be argued to be to have HTTP based APIs that define some URI layout and maybe only use generic media types. It is certainly more useful than doing the same API with RMI, SOAP or CORBA.
> 
> However, given there is no name for them, they simple become 'REST-APIs' which obfuscates the fact that systems using those APIs will *not* have the properties induced by REST.
> 
> If we name them, differentiation between the two becomes a lot easier.
> 
> 
> What I lack is a compelling name that sounds cool enough so API owners can still be proud even if they are not (yet) in the REST-Olymp of things :-) ?
> 
> Any ideas?
> 
> 
> HTTP-base APIs
> Fixed-URI-APIs
> 
> Both *not* cool....
> 
> Jan
> 
> 
> 
> -----------------------------------
>  Jan Algermissen, Consultant
>  NORD Software Consulting
> 
>  Mail: algermissen@...
>  Blog: http://www.nordsc.com/blog/
>  Work: http://www.nordsc.com/
> -----------------------------------
>

CR - Cloud Resource

Additional thought:

In a sense, the APIs in question do make use of hypermedia. They just use it at design time by making the server's state machine static. This information is then published as *hypermedia* for *design time* consumption instead of runtime consumption.

The consequence is of course that client and server are coupled by their original design[1]. However, systems still benefit from the induced simplicity by this 'style' so it should not be ruled out as such, just be correctly understood.


An appropriate name would maybe have to emphasize the satic nature of the use of hypermedia?

Resource Orientation with Static Hypermedia (ROSH)
Resource Oriented and Coupled (ROAC)

etc.



Jan




[1] http://tech.groups.yahoo.com/group/rest-discuss/message/8377


On Feb 16, 2010, at 9:39 PM, Jan Algermissen wrote:

> Given that the creation of APIs that ignore the hypermedia constraint is undeniably an ongoing activity wouldn't it be nice to give those a name in order to differentiate them from RESTful APIs?
> 
> I think that it can in various circumstances be argued to be to have HTTP based APIs that define some URI layout and maybe only use generic media types. It is certainly more useful than doing the same API with RMI, SOAP or CORBA.
> 
> However, given there is no name for them, they simple become 'REST-APIs' which obfuscates the fact that systems using those APIs will *not* have the properties induced by REST.
> 
> If we name them, differentiation between the two becomes a lot easier.
> 
> 
> What I lack is a compelling name that sounds cool enough so API owners can still be proud even if they are not (yet) in the REST-Olymp of things :-) ?
> 
> Any ideas?
> 
> 
> HTTP-base APIs
> Fixed-URI-APIs
> 
> Both *not* cool....
> 
> Jan
> 
> 
> 
> -----------------------------------
> Jan Algermissen, Consultant
> NORD Software Consulting
> 
> Mail: algermissen@...
> Blog: http://www.nordsc.com/blog/
> Work: http://www.nordsc.com/
> -----------------------------------
> 
> 
> 
> 
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

--- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
>
> Additional thought:
> 
> In a sense, the APIs in question do make use of hypermedia. They just use it at design time by making the server's state machine static. This information is then published as *hypermedia* for *design time* consumption instead of runtime consumption.
> 
> The consequence is of course that client and server are coupled by their original design[1]. However, systems still benefit from the induced simplicity by this 'style' so it should not be ruled out as such, just be correctly understood.
> 
> 
> An appropriate name would maybe have to emphasize the satic nature of the use of hypermedia?
> 
> Resource Orientation with Static Hypermedia (ROSH)
> Resource Oriented and Coupled (ROAC)
> 
> etc.
> 
> Jan
>  
> [1] http://tech.groups.yahoo.com/group/rest-discuss/message/8377
> 

I'm not sure if design-time, "static hypermedia" makes sense. From the message you quoted:
     Hypermedia means the placement of controls within the 
     presentation of information 
If the links and controls aren't in the data communicated at runtime, then I think it's a stretch to call it "hypermedia".

How about "Pure Data Resources" or "Data-Only Resources"?

Andrew

> 
> Interesting. I claim there's no difference at all between options two
> and three, as at least from a REST perspective there's no difference
> between a query parameter and a file extension.
> 
> I wonder why you'd disagree?
> 

Because this is a common misconception that arises from the notion of
URI opacity.  REST's notion of opaque URIs does not somehow override RFC
3986, which transparently declares quite some difference between path
and query.  Roy would say, "[Q]uery is not a substitute for
identification of resources."

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-720

Just think about how any httpd handles incoming requests.  If the query
is being used as a filename extension (violating the Identification of
Resources constraint), then you'd have some processing to do in order
to attach the query data to the path data before continuing.  Using a
filename extension requires no such query processing at the server.

So clearly, they are not the same.  Since URIs are opaque, there is no
way for an intermediary to determine that the query is being mis-used
as a filename extension.  It is well known that intermediaries tend not
to cache responses to requests containing queries.  The use of a
filename extension as a filename extension is well understood by
intermediaries, whereas using a query as a filename extension is not.

-Eric

On Feb 17, 2010, at 9:34 PM, Eric J. Bowman wrote:

>> 
>> Interesting. I claim there's no difference at all between options two
>> and three, as at least from a REST perspective there's no difference
>> between a query parameter and a file extension.
>> 
>> I wonder why you'd disagree?
>> 
> 
> Because this is a common misconception that arises from the notion of
> URI opacity.  REST's notion of opaque URIs does not somehow override RFC
> 3986, which transparently declares quite some difference between path
> and query.  Roy would say, "[Q]uery is not a substitute for
> identification of resources."
> 
> http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-720
> 

I don't interpret this the same way; it would be interesting to get Roy's take on this.

> Just think about how any httpd handles incoming requests.  If the query
> is being used as a filename extension (violating the Identification of
> Resources constraint), then you'd have some processing to do in order
> to attach the query data to the path data before continuing.  Using a
> filename extension requires no such query processing at the server.

I'm not sure I get what you're saying. Using or not using something like mod_rewrite to turn "?format=pdf" into ".pdf" does not change anything with regards to RESTful HTTP usage from my understanding.

> 
> So clearly, they are not the same.  Since URIs are opaque, there is no
> way for an intermediary to determine that the query is being mis-used
> as a filename extension.  It is well known that intermediaries tend not
> to cache responses to requests containing queries.  

That used to be true, particularly for Squid, but is no longer the case. Even so, other intermediaries don't cache anything by default; I don't see how that would support your argument either.

> The use of a
> filename extension as a filename extension is well understood by
> intermediaries, whereas using a query as a filename extension is not.
> 

IMO any intermediary making such as a distinction is broken. But in any case, I'd be interested which ones this applies to?

Best,
Stefan

> -Eric

>
>
> > The use of a
> > filename extension as a filename extension is well understood by
> > intermediaries, whereas using a query as a filename extension is not.
> >
>
As Stefan pointed out... if a intermediate knows that your specific
resources provided by your server works in that way, that is something that
broke the uniform interface: the http protocol + URIs did not specify that,
that is private knowledge from your own system, thus your intermediate will
break with other systems.

In reality, a lot of people will use it because they find content negotation
through any headers that affect the Vary header response something default
to implement.

Creating a pure Rails app, conneg through Accept is actually working
partially because of well known problems of some browsers, which is a pity:
it works for the browser, but if your client and intermediate layers work as
properly, your application will not.

I would go for Accept,Accept-Language,User-Agent,Alternate headers (with a
hypermedia representation in a response body when providing a 406)..

The question would be, why people still go for .xml, .json and ?format
alternatives?
In my opinion, other alternatives only exist because of the lack of a REST
client api that supports them...
Developers use http client libraries to access resources, believing they are
benefiting from REST advantages, therefore they do no conneg at all, just
GET whatever.xml: their libraries do not support content negotiation, unless
you it on your own.

But now my answer will start to run off the desired topic and get into what
I would love to see and implement in trendy http client libraries in order
to make them REST, not just http.

Regards

Guilherme Silveira

Let's put this much more simply.  Say we have:

/resource?format=pdf
/resource?format=html

What happens if I curl each one in succession?  Well, curl will save
the first as 'resource' and the second as 'resource.1'.  If conneg is
enabled at /resource, and we use curl to send appropriate Accept
headers, it will still save the files as 'resource' and 'resource.1'
because curl ignores the query -- whether it's part of the requested
URL or sent in a Content-Location response header.

Question:  Is curl broken, or is the server getting RFC 3986 wrong,
thereby violating REST's Identification of Resources constraint, which
requires us (for all intents and purposes) to obey RFC 3986?

"
All URI references are parsed by generic syntax parsers when used.(...)
URI scheme specifications can define opaque identifiers by disallowing
use of slash characters, question mark characters, and the URIs
"scheme:." and "scheme:..".
"

The HTTP scheme is *not* opaque, because it allows '/', '.', '..' and
'?'.  I don't care if the generic-syntax URI parser is in curl or in an
intermediary's client connector or in the origin's server connector.  It
must handle the request in a non-generic fashion (i.e. by using
mod_rewrite) to correlate a query with a file format, whereas using a
filename extension is an unambiguous method of solving this problem,
which has the benefit of "flowing naturally, in harmony with the
system".

To the extent that curl will know to save resource.pdf and resource.html
to disk, as will anything based on generic URI parsing.  The saved PDF
representation may be opened in the proper application automatically.
The common understanding encapsulated in RFC 3986 is that, "The query
component contains non-hierarchical data...".  I contend that the format
of a representation is part of a system's hierarchical data.  The proof
is right there in curl, which sees no hierarchy when it's saving
'resource' and 'resource.1' to disk, while obviously recognizing .pdf
and .html as part of a hierarchy of representations, whether by direct
dereferencing or by presence in a Content-Location response header.

The demo I recently posted shows exactly what is meant by URI opacity
in REST.  The client-side XSLT code (which describes the API) could
care less about the URI allocation scheme, aside from sometimes checking
for the presence of a fragment (like '/' and '?', the octothorpe is a
reserved character in URIs), or generating relative URLs based on the
hierarchy of my allocation scheme.

But it's still treating URIs opaquely -- links are derived from the
link relations in the source documents, which are read from @href's.
There is no analysis of those @href contents by keyword or filename
extension to determine "resource type".  Clients aren't required to know
any specifics of a URI's pattern.  That would be coupling, which is
diametrically opposed to the notion of URI opacity in REST.

Don't get carried away by saying that my treating URIs as hierarchical
or testing whether they have fragments or not, amounts to a failure to
treat URIs as opaque.  Can you point to some constraint in REST that
I'm breaking?  Can you find any support from Roy to back up this notion
that URI opacity means that query and filename extension are the same?
Are there any generic URI parsers you can point me to, which treat
query strings opaquely?  Or do they all consider '?' to be a reserved
character?

I simply find no support in REST for this extreme notion that URIs
can't be treated as hierarchical, or that it's an error to consider a
query string any differently than a filename extension.  In fact, the
only reference I can find in REST to anything being "opaque" is cookies.
So the onus is not on me to prove that Roy isn't being clear as daylight
when he says that "query is not a substitute for identification of
resources", but on you who think it could possibly mean any different
to support *your* arguments.  :-)

-Eric

> 
> The demo I recently posted shows exactly what is meant by URI opacity
> in REST.  The client-side XSLT code (which describes the API) could
> care less about the URI allocation scheme, aside from sometimes
> checking for the presence of a fragment (like '/' and '?', the
> octothorpe is a reserved character in URIs), or generating relative
> URLs based on the hierarchy of my allocation scheme.
> 

There is a REST mismatch in my XSLT code, sometimes I'm doing substring-
before($known-string) when generating URLs.  This is a pragmatic
solution to the limitations of Xpath 1 -- I'd rather do substring-before
(last-instance-of-'/'), which would be a more opaque handling of the
URL, but the resulting code would be more complex than would be worth
maintaining.  So a comment is placed in the code, noting the deficiency.

-Eric

For those who has no hypermedia support at all: Almost There REST?

> In a sense, the APIs in question do make use of hypermedia. They just use
it at design time by making the server's state machine static. This
information is then published as *hypermedia* for *design time* consumption
instead of runtime consumption.
Unfortunately, sounds like all REST frameworks manuals I've read so far
(including my own) that include hypermedia support: late binding on uri's
but early binding on protocol design.

Noting that binding is always there - its just a matter of how much bound
you are - calling it "Resource Oriented and Coupled" might be too harsh.

I believe your current series of blog posts might help creating procurement
examples with lesser binding in that way.

Regards

Guilherme Silveira
Caelum | Ensino e Inova��o
http://www.caelum.com.br/


On Wed, Feb 17, 2010 at 10:04 AM, Jan Algermissen
<algermissen1971@...>wrote:

>
>
> Additional thought:
>
> In a sense, the APIs in question do make use of hypermedia. They just use
> it at design time by making the server's state machine static. This
> information is then published as *hypermedia* for *design time* consumption
> instead of runtime consumption.
>
> The consequence is of course that client and server are coupled by their
> original design[1]. However, systems still benefit from the induced
> simplicity by this 'style' so it should not be ruled out as such, just be
> correctly understood.
>
> An appropriate name would maybe have to emphasize the satic nature of the
> use of hypermedia?
>
> Resource Orientation with Static Hypermedia (ROSH)
> Resource Oriented and Coupled (ROAC)
>
> etc.
>
> Jan
>
> [1] http://tech.groups.yahoo.com/group/rest-discuss/message/8377
>
>
> On Feb 16, 2010, at 9:39 PM, Jan Algermissen wrote:
>
> > Given that the creation of APIs that ignore the hypermedia constraint is
> undeniably an ongoing activity wouldn't it be nice to give those a name in
> order to differentiate them from RESTful APIs?
> >
> > I think that it can in various circumstances be argued to be to have HTTP
> based APIs that define some URI layout and maybe only use generic media
> types. It is certainly more useful than doing the same API with RMI, SOAP or
> CORBA.
> >
> > However, given there is no name for them, they simple become 'REST-APIs'
> which obfuscates the fact that systems using those APIs will *not* have the
> properties induced by REST.
> >
> > If we name them, differentiation between the two becomes a lot easier.
> >
> >
> > What I lack is a compelling name that sounds cool enough so API owners
> can still be proud even if they are not (yet) in the REST-Olymp of things
> :-) ?
> >
> > Any ideas?
> >
> >
> > HTTP-base APIs
> > Fixed-URI-APIs
> >
> > Both *not* cool....
> >
> > Jan
> >
> >
> >
> > -----------------------------------
> > Jan Algermissen, Consultant
> > NORD Software Consulting
> >
> > Mail: algermissen@... <algermissen%40acm.org>
> > Blog: http://www.nordsc.com/blog/
> > Work: http://www.nordsc.com/
> > -----------------------------------
> >
> >
> >
> >
> >
> >
> > ------------------------------------
> >
> > Yahoo! Groups Links
>
> >
> >
> >
>
> -----------------------------------
> Jan Algermissen, Consultant
> NORD Software Consulting
>
> Mail: algermissen@... <algermissen%40acm.org>
> Blog: http://www.nordsc.com/blog/
> Work: http://www.nordsc.com/
> -----------------------------------
>
>  
>

>
> I'm not sure if design-time, "static hypermedia" makes sense. From the
> message you quoted:
> Hypermedia means the placement of controls within the
> presentation of information
> If the links and controls aren't in the data communicated at runtime, then
> I think it's a stretch to call it "hypermedia".
>
If I got it right, the API in question uses hypermedia to represent state
transitions that were agreed upon a priori by both server and consumers.

I believe the difference here is that if such state transitions were made
through resource handling on the http level, using well known and accepted
relation types, you server has published a resource that can be used by
clients that did not need to write specific code to deal with it.
So, hypermedia is there, its just that the client is consuming it in a
less-but-still-early-binding fashion.

Jan, is that the case?

Regards


> How about "Pure Data Resources" or "Data-Only Resources"?
>
> Andrew
>
>  
>

Query strings shouldn't have anything to do with content negotiation,
and it is an error to couple the two together.  Consider my not-yet-
ready-for-prime-time Simple Web Service:  say I want to know what day
of the week St. Patrick's Day falls on this year, in English:

http://en.wiski.org/date?iso=2010-03-17

Wednesday?  That sucks.  Friday's best...  Notice the output is XHTML.
Well, that's just for now.  Eventually, that URI will negotiate between
these two variants (these URLs will appear in Content-Location):

http://en.wiski.org/date.xht?iso=2010-03-17
http://en.wiski.org/date.json?iso=2010-03-17

The query won't be considered in conneg, only the path.  The query is
handled separately.  The best advice I can give anyone asking about
conneg, is to keep the query out of it, if for no other reason than for
separation of concerns -- hierarchical data like output format belongs
in the path.  The following request will eventually redirect based on
language negotiation:

http://wiski.org/date?iso=2010-03-17

The workflow of redirecting to the proper language prefix, then
negotiating an output format, only works if the query is passed along
as an appendage.  To consider the query within those workflows would go
against the notion of URI opacity, and require the implementation of
additional steps.  As it is, the URIs are self-explanatory:  A resource,
/date, having two variants /date.xht and /date.json, is what's being
queried.

The /date resource is described simply as a converter of ISO 8601 date
strings to human language.  What machine language that human language
is returned in, isn't part of the /date resource description.  It has
no relevance to the query being made.  It's part of the protocol layer.
If I make an OPTIONS request (eventually) to http://en.wiski.org/date
?iso=2010-03-17, I'll get back a list containing /date.xht
?iso=2010-03-17 and /date.json?iso=2010-03-17 in a 300 Multiple Choices
response.

In the future, I can omit the Accept header and request /date.json
directly for any query.  Considering the query when performing conneg
adds an entire layer of complexity.  It's best ignored, in favor of
conneg based on Accept header, with variants as their own resources
with their own URLs using filename extensions.  After all, output
format is part of the protocol layer (late binding of representation to
resource).  Protocol operations (conneg) shouldn't involve query
strings -- only headers.

If a server can't perform content negotiation before parsing the query,
then content negotiation isn't being performed at the protocol layer,
it's based on non-opaque knowledge of the query string itself, and that
knowledge cannot be deciphered by any intermediary.  So I can't stress
enough, to base conneg on Accept headers and filename extensions, never
query strings.  Query strings shouldn't have anything to do with
protocol-layer concerns, they're strictly application-layer concerns to
be considered *after* content negotiation has occurred.

In the case of my /date service, conneg may occur twice before the
server even knows what handler to pass that query *to*.  As opposed to
having a single handler deciphering the query string, deciding output
format at the application layer.  I dispatch the query to a handler as
determined by the Accept header.  Huge architectural difference, there.

Finally, no media type identifier describes registered "queries" for
the media type.  They do, however, in many cases, describe registered
filename extensions.  Using query as filename extension simply goes
against common best practice, whereas REST embraces common best
practices.

-Eric

On Feb 18, 2010, at 4:12 AM, Guilherme Silveira wrote:

> For those who has no hypermedia support at all: Almost There REST?
> 
> > In a sense, the APIs in question do make use of hypermedia. They just use it at design time by making the server's state machine static. This information is then published as *hypermedia* for *design time* consumption instead of runtime consumption.
> Unfortunately, sounds like all REST frameworks manuals I've read so far (including my own) that include hypermedia support: late binding on uri's but early binding on protocol design.
> 
> Noting that binding is always there - its just a matter of how much bound you are

Sorry, I am having trouble to understand. Can you re-word?


> - calling it "Resource Oriented and Coupled" might be too harsh.
> 
> I believe your current series of blog posts might help creating procurement examples with lesser binding in that way.
> 

About to show how I think that would work, but I keep being distracted by other things.

Jan




> Regards
> 
> Guilherme Silveira
> Caelum | Ensino e Inova��o
> http://www.caelum.com.br/
> 
> 
> On Wed, Feb 17, 2010 at 10:04 AM, Jan Algermissen <algermissen1971@...> wrote:
>  
> Additional thought:
> 
> In a sense, the APIs in question do make use of hypermedia. They just use it at design time by making the server's state machine static. This information is then published as *hypermedia* for *design time* consumption instead of runtime consumption.
> 
> The consequence is of course that client and server are coupled by their original design[1]. However, systems still benefit from the induced simplicity by this 'style' so it should not be ruled out as such, just be correctly understood.
> 
> An appropriate name would maybe have to emphasize the satic nature of the use of hypermedia?
> 
> Resource Orientation with Static Hypermedia (ROSH)
> Resource Oriented and Coupled (ROAC)
> 
> etc.
> 
> Jan
> 
> [1] http://tech.groups.yahoo.com/group/rest-discuss/message/8377
> 
> 
> 
> On Feb 16, 2010, at 9:39 PM, Jan Algermissen wrote:
> 
> > Given that the creation of APIs that ignore the hypermedia constraint is undeniably an ongoing activity wouldn't it be nice to give those a name in order to differentiate them from RESTful APIs?
> > 
> > I think that it can in various circumstances be argued to be to have HTTP based APIs that define some URI layout and maybe only use generic media types. It is certainly more useful than doing the same API with RMI, SOAP or CORBA.
> > 
> > However, given there is no name for them, they simple become 'REST-APIs' which obfuscates the fact that systems using those APIs will *not* have the properties induced by REST.
> > 
> > If we name them, differentiation between the two becomes a lot easier.
> > 
> > 
> > What I lack is a compelling name that sounds cool enough so API owners can still be proud even if they are not (yet) in the REST-Olymp of things :-) ?
> > 
> > Any ideas?
> > 
> > 
> > HTTP-base APIs
> > Fixed-URI-APIs
> > 
> > Both *not* cool....
> > 
> > Jan
> > 
> > 
> > 
> > -----------------------------------
> > Jan Algermissen, Consultant
> > NORD Software Consulting
> > 
> > Mail: algermissen@...
> > Blog: http://www.nordsc.com/blog/
> > Work: http://www.nordsc.com/
> > -----------------------------------
> > 
> > 
> > 
> > 
> > 
> > 
> > ------------------------------------
> > 
> > Yahoo! Groups Links
> 
> > 
> > 
> > 
> 
> -----------------------------------
> Jan Algermissen, Consultant
> NORD Software Consulting
> 
> Mail: algermissen@...
> Blog: http://www.nordsc.com/blog/
> Work: http://www.nordsc.com/
> -----------------------------------
> 
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

On Feb 18, 2010, at 4:15 AM, Guilherme Silveira wrote:

> 
> 
> I'm not sure if design-time, "static hypermedia" makes sense. From the message you quoted:
> Hypermedia means the placement of controls within the 
> presentation of information 
> If the links and controls aren't in the data communicated at runtime, then I think it's a stretch to call it "hypermedia".
> If I got it right, the API in question uses hypermedia to represent state transitions that were agreed upon a priori by both server and consumers.

Yes, that is what I mean.
I know it is not really correct to put it that way, but it occurred to me that a description of the available URIs at design time is in some sense similar to such a description at run time. It is 'just' the amount of design time coupling induced that differs.

Consider WADL at runtime (which is RESTful[1] because you can consider it a form) vs. WADL at design time.

If we manage to make designers of 3/4 APIs aware of the coupling they introduce and show them the tradeoffs involved, that would be beneficial in many ways:

- clear up the confusion in general
- emphazise what RESTfulness means
- educate how coupled 3/4 systems actually are
- provide a ground for analyzing the tradeoffs of 3/4 systems, e.g. I might
  choose not to go through the 'pain' of the media type design and maintenance
  and instead put my resources in place, descipe the URIs and payloads
  and ready is my service. As long as I make *very* clear that there is
  a lot of coupling going on and that I effectively cannot change my service
  without consulting the client owner the resukt will be a manageable system.
  For some situations, the very short time to production and benefits in
  'debugability' make 3/4 systems far superior to any form of RPC.
  Just be sure you do not think it is REST.

> 
> I believe the difference here is that if such state transitions were made through resource handling on the http level, using well known and accepted relation types, you server has published a resource that can be used by clients that did not need to write specific code to deal with it.
> So, hypermedia is there, its just that the client is consuming it in a less-but-still-early-binding fashion.
> 
> Jan, is that the case?

Hmm, sorry - I did not get the essence of your point. Try again?

Jan


[1] Though I do not like to use such a generic 'form' meachanism; I prefer business level documents




> 
> Regards
> 
> 
> How about "Pure Data Resources" or "Data-Only Resources"?
> 
> Andrew
> 
> 
> 
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

In procurement domains/processes, there usually exist order document and order-change documents (see UBL for example).

Suppose I create an order by POSTing an order document to some order accepting resource.

POST /orders/
Content-Type: application/procurement+xml;type=order

<order ... />

201 Created
Location: /orders/1
Content-Location: /orders/1
ETag: "1234"
Content-Type: application/procurement+xml;type=order

<order .../>


What do you think about viewing an order-change document as a diff I can apply to an order:

PATCH /orders/1
Content-Type: application/procurement+xml;type=order-change
If-Match: "1234"

<orderChange .../>

200 Ok
Content-Location: /orders/1
ETag: "1235"
Content-Type: application/procurement+xml;type=order

<order .../>


I think the considerably open semantics of PATCH do at least not forbid that.

Any thoughts?


Jan






-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

On Feb 18, 2010, at 11:15 AM, Sebastien Lambla wrote:

> Quick note on this...
>  
> Hypermedia controls are part of hypermedia document. That's things linking to things.
>  
> If you pre-define statically all the URIs for your state transitions, you *do not have* hypermedia controls. You have static endpoinds a la SOAP. And that's because you don't have hypermedia documents.

Yes, sure I am bending the point. But a design time form is still not very different from a run time form. Except for the induced coupling of course.

I am not trying to say that the other APIs are somehow also REST. I am trying to explicitly label them as something so we can say: Foo APIs are Foo APIs *NOT* REST APIs.

If you have two childre, you do not call one of them Jim and the other one "Jim with black hair" or "Small Jim" or whatever.


Jan



>  
> *if* you delegated some of those endpoints definitions to some discovery mechanism a la UDDI, then maybe you've managed to reintroduce the hypermedia documents, but then you've gone full circle in reinventing the wheel.
> 
>  
> > CC: andrew.wahbe@...; rest-discuss@yahoogroups.com
> > To: guilherme.silveira@...
> > From: algermissen1971@...
> > Date: Thu, 18 Feb 2010 08:38:01 +0100
> > Subject: Re: [rest-discuss] Re: A Name for "3 out of 4 REST constraints" APIs?
> > 
> > 
> > On Feb 18, 2010, at 4:15 AM, Guilherme Silveira wrote:
> > 
> > > 
> > > 
> > > I'm not sure if design-time, "static hypermedia" makes sense. From the message you quoted:
> > > Hypermedia means the placement of controls within the 
> > > presentation of information 
> > > If the links and controls aren't in the data communicated at runtime, then I think it's a stretch to call it "hypermedia".
> > > If I got it right, the API in question uses hypermedia to represent state transitions that were agreed upon a priori by both server and consumers.
> > 
> > Yes, that is what I mean.
> > I know it is not really correct to put it that way, but it occurred to me that a description of the available URIs at design time is in some sense similar to such a description at run time. It is 'just' the amount of design time coupling induced that differs.
> > 
> > Consider WADL at runtime (which is RESTful[1] because you can consider it a form) vs. WADL at design time.
> > 
> > If we manage to make designers of 3/4 APIs aware of the coupling they introduce and show them the tradeoffs involved, that would be beneficial in many ways:
> > 
> > - clear up the confusion in general
> > - emphazise what RESTfulness means
> > - educate how coupled 3/4 systems actually are
> > - provide a ground for analyzing the tradeoffs of 3/4 systems, e.g. I might
> > choose not to go through the 'pain' of the media type design and maintenance
> > and instead put my resources in place, descipe the URIs and payloads
> > and ready is my service. As long as I make *very* clear that there is
> > a lot of coupling going on and that I effectively cannot change my service
> > without consulting the client owner the resukt will be a manageable system.
> > For some situations, the very short time to production and benefits in
> > 'debugability' make 3/4 systems far superior to any form of RPC.
> > Just be sure you do not think it is REST.
> > 
> > > 
> > > I believe the difference here is that if such state transitions were made through resource handling on the http level, using well known and accepted relation types, you server has published a resource that can be used by clients that did not need to write specific code to deal with it.
> > > So, hypermedia is there, its just that the client is consuming it in a less-but-still-early-binding fashion.
> > > 
> > > Jan, is that the case?
> > 
> > Hmm, sorry - I did not get the essence of your point. Try again?
> > 
> > Jan
> > 
> > 
> > [1] Though I do not like to use such a generic 'form' meachanism; I prefer business level documents
> > 
> > 
> > 
> > 
> > > 
> > > Regards
> > > 
> > > 
> > > How about "Pure Data Resources" or "Data-Only Resources"?
> > > 
> > > Andrew
> > > 
> > > 
> > > 
> > > 
> > > 
> > > 
> > 
> > -----------------------------------
> > Jan Algermissen, Consultant
> > NORD Software Consulting
> > 
> > Mail: algermissen@...
> > Blog: http://www.nordsc.com/blog/
> > Work: http://www.nordsc.com/
> > -----------------------------------
> > 
> > 
> > 
> > 
> > 
> > 
> > ------------------------------------
> > 
> > Yahoo! Groups Links
> > 
> > 
> > 
> 
> Do you have a story that started on Hotmail? Tell us now

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Quick note on this...

 

Hypermedia controls are part of hypermedia document. That's things linking to things.

 

If you pre-define statically all the URIs for your state transitions, you *do not have* hypermedia controls. You have static endpoinds a la SOAP. And that's because you don't have hypermedia documents.

 

*if* you delegated some of those endpoints definitions to some discovery mechanism a la UDDI, then maybe you've managed to reintroduce the hypermedia documents, but then you've gone full circle in reinventing the wheel.


 
> CC: andrew.wahbe@...; rest-discuss@yahoogroups.com
> To: guilherme.silveira@...
> From: algermissen1971@...m
> Date: Thu, 18 Feb 2010 08:38:01 +0100
> Subject: Re: [rest-discuss] Re: A Name for "3 out of 4 REST constraints" APIs?
> 
> 
> On Feb 18, 2010, at 4:15 AM, Guilherme Silveira wrote:
> 
> > 
> > 
> > I'm not sure if design-time, "static hypermedia" makes sense. From the message you quoted:
> > Hypermedia means the placement of controls within the 
> > presentation of information 
> > If the links and controls aren't in the data communicated at runtime, then I think it's a stretch to call it "hypermedia".
> > If I got it right, the API in question uses hypermedia to represent state transitions that were agreed upon a priori by both server and consumers.
> 
> Yes, that is what I mean.
> I know it is not really correct to put it that way, but it occurred to me that a description of the available URIs at design time is in some sense similar to such a description at run time. It is 'just' the amount of design time coupling induced that differs.
> 
> Consider WADL at runtime (which is RESTful[1] because you can consider it a form) vs. WADL at design time.
> 
> If we manage to make designers of 3/4 APIs aware of the coupling they introduce and show them the tradeoffs involved, that would be beneficial in many ways:
> 
> - clear up the confusion in general
> - emphazise what RESTfulness means
> - educate how coupled 3/4 systems actually are
> - provide a ground for analyzing the tradeoffs of 3/4 systems, e.g. I might
> choose not to go through the 'pain' of the media type design and maintenance
> and instead put my resources in place, descipe the URIs and payloads
> and ready is my service. As long as I make *very* clear that there is
> a lot of coupling going on and that I effectively cannot change my service
> without consulting the client owner the resukt will be a manageable system.
> For some situations, the very short time to production and benefits in
> 'debugability' make 3/4 systems far superior to any form of RPC.
> Just be sure you do not think it is REST.
> 
> > 
> > I believe the difference here is that if such state transitions were made through resource handling on the http level, using well known and accepted relation types, you server has published a resource that can be used by clients that did not need to write specific code to deal with it.
> > So, hypermedia is there, its just that the client is consuming it in a less-but-still-early-binding fashion.
> > 
> > Jan, is that the case?
> 
> Hmm, sorry - I did not get the essence of your point. Try again?
> 
> Jan
> 
> 
> [1] Though I do not like to use such a generic 'form' meachanism; I prefer business level documents
> 
> 
> 
> 
> > 
> > Regards
> > 
> > 
> > How about "Pure Data Resources" or "Data-Only Resources"?
> > 
> > Andrew
> > 
> > 
> > 
> > 
> > 
> > 
> 
> -----------------------------------
> Jan Algermissen, Consultant
> NORD Software Consulting
> 
> Mail: algermissen@...
> Blog: http://www.nordsc.com/blog/
> Work: http://www.nordsc.com/
> -----------------------------------
> 
> 
> 
> 
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 
 		 	   		  
_________________________________________________________________
Send us your Hotmail stories and be featured in our newsletter
http://clk.atdmt.com/UKM/go/195013117/direct/01/

On Thu, Feb 18, 2010 at 21:15, Sebastien Lambla <seb@...> wrote:
> Hypermedia controls are part of hypermedia document. That's things linking to things.

Linking is only part of it, of course. How about ;

  Interactive Resource Orientation vs. Non-interactive? (Interactive
at least denotes a semblance of non-static interfaces)


Regards,

Alex
--
Project Wrangler, SOA, Information Alchemist, UX, RESTafarian, Topic Maps
--- http://shelter.nu/blog/ ----------------------------------------------
------------------ http://www.google.com/profiles/alexander.johannesen ---

On Thu, Feb 18, 2010 at 2:20 AM, Jan Algermissen
<algermissen1971@...> wrote:
> In procurement domains/processes, there usually exist order document and order-change
> documents (see UBL for example).
[...]
> What do you think about viewing an order-change document as a diff I can apply to an order:
>
> PATCH /orders/1

One problem might be that frequently order changes should be resources
(usually called Change Orders) in their own right.  For example,
sometimes order changes invoke extra charges.

In that case, the trading partners might want three resources:  the
original order, the change order, and the changed order (after the
change was applied).

Good point.  It becomes a matter of media type design -- can you create
a media type which you can dereference as a 'change order' *and* use as
a diff format for PATCH?

-Eric

Bob Haugen wrote:

> On Thu, Feb 18, 2010 at 2:20 AM, Jan Algermissen
> <algermissen1971@...> wrote:
> > In procurement domains/processes, there usually exist order
> > document and order-change documents (see UBL for example).
> [...]
> > What do you think about viewing an order-change document as a diff
> > I can apply to an order:
> >
> > PATCH /orders/1
> 
> One problem might be that frequently order changes should be resources
> (usually called Change Orders) in their own right.  For example,
> sometimes order changes invoke extra charges.
> 
> In that case, the trading partners might want three resources:  the
> original order, the change order, and the changed order (after the
> change was applied).
> 

rest-wheas

whithout hipermedia engine of application state


_________________________________________________

Melhores cumprimentos / Beir beannacht / Best regards

Ant�nio Manuel dos Santos Mota

http://card.ly/amsmota
_________________________________________________



2010/2/18 Alexander Johannesen <alexander.johannesen@...>

>
>
> On Thu, Feb 18, 2010 at 21:15, Sebastien Lambla <seb@...<seb%40serialseb.com>>
> wrote:
> > Hypermedia controls are part of hypermedia document. That's things
> linking to things.
>
> Linking is only part of it, of course. How about ;
>
> Interactive Resource Orientation vs. Non-interactive? (Interactive
> at least denotes a semblance of non-static interfaces)
>
> Regards,
>
> Alex
> --
> Project Wrangler, SOA, Information Alchemist, UX, RESTafarian, Topic Maps
> --- http://shelter.nu/blog/ ----------------------------------------------
> ------------------ http://www.google.com/profiles/alexander.johannesen ---
>  
>

Or just

rest-wh


_________________________________________________

Melhores cumprimentos / Beir beannacht / Best regards

Ant�nio Manuel dos Santos Mota

http://card.ly/amsmota
_________________________________________________



2010/2/18 Ant�nio Mota <amsmota@...>

> rest-wheas
>
> whithout hipermedia engine of application state
>
>
> _________________________________________________
>
> Melhores cumprimentos / Beir beannacht / Best regards
>
> Ant�nio Manuel dos Santos Mota
>
> http://card.ly/amsmota
> _________________________________________________
>
>
>
> 2010/2/18 Alexander Johannesen <alexander.johannesen@...>
>
>
>>
>> On Thu, Feb 18, 2010 at 21:15, Sebastien Lambla <seb@...<seb%40serialseb.com>>
>> wrote:
>> > Hypermedia controls are part of hypermedia document. That's things
>> linking to things.
>>
>> Linking is only part of it, of course. How about ;
>>
>> Interactive Resource Orientation vs. Non-interactive? (Interactive
>> at least denotes a semblance of non-static interfaces)
>>
>> Regards,
>>
>> Alex
>> --
>> Project Wrangler, SOA, Information Alchemist, UX, RESTafarian, Topic Maps
>> --- http://shelter.nu/blog/----------------------------------------------
>> ------------------ http://www.google.com/profiles/alexander.johannesen---
>>  
>>
>
>

RESTless

On Feb 18, 2010, at 1:19 PM, Bob Haugen wrote:

> RESTless

:-)

But having REST in the name obfuscates the message (IMHO) that it is something different.



Jan



> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Well, with REST-WHEAS that doesn't happen because

- the "-" can be understood as "minus"

- WHEAS for rest-aware people is similiar enough to HATEOAS to immediately
be recognizable

- 3/4 of REST is almost REST, so it is convenient that people understand
that is a valid approach to a future full-implementation of REST.


So people can say - my app is REST-WHEAS until I have the time to implement
the rest... the rest of REST...
_________________________________________________

Melhores cumprimentos / Beir beannacht / Best regards

Ant�nio Manuel dos Santos Mota

http://card.ly/amsmota
_________________________________________________



2010/2/18 Jan Algermissen <algermissen1971@...>

>
>
>
> On Feb 18, 2010, at 1:19 PM, Bob Haugen wrote:
>
> > RESTless
>
> :-)
>
> But having REST in the name obfuscates the message (IMHO) that it is
> something different.
>
> Jan
>
> >
> >
> > ------------------------------------
> >
> > Yahoo! Groups Links
>
> >
> >
> >
>
> -----------------------------------
> Jan Algermissen, Consultant
> NORD Software Consulting
>
> Mail: algermissen@... <algermissen%40acm.org>
> Blog: http://www.nordsc.com/blog/
> Work: http://www.nordsc.com/
> -----------------------------------
>
>  
>

> <http://en.wikipedia.org/wiki/George_Forman>.

<http://en.wikipedia.org/wiki/George_Foreman>.

Sincerely yours, the editor.

Jan Algermissen (in
<http://tech.groups.yahoo.com/group/rest-discuss/message/14786>):

> If you have two [children], you do not call one of them ["Jim"] and the other one "Jim with black hair" or "Small Jim" or whatever.

<http://en.wikipedia.org/wiki/George_Forman>.

On Feb 18, 2010, at 2:49 PM, Etan Wexler wrote:

> Jan Algermissen (in
> <http://tech.groups.yahoo.com/group/rest-discuss/message/14786>):
> 
>> If you have two [children], you do not call one of them ["Jim"] and the other one "Jim with black hair" or "Small Jim" or whatever.
> 
> <http://en.wikipedia.org/wiki/George_Forman>.

:-)

I once played pool with two huge white South Africans that were *single-egged twins*. One of them said:

"Hi I am Neil and this is my brother Neil"

Jan



> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

> I think the considerably open semantics of PATCH do at least not forbid that.

IMHO,� PATCH does not define which media type can be used, so content
negotiation should handle it as usual: you can either accept a
type=order with a partial representation of your resource, or
type=order-change with some change specific values.

Regards

Guilherme

My brother is also called Ian. We differ by middle name.

ian



On 18 Feb 2010, at 14:49, Etan Wexler <yahoo.com@...> wrote:

> Jan Algermissen (in
> <http://tech.groups.yahoo.com/group/rest-discuss/message/14786>):
>
> > If you have two [children], you do not call one of them ["Jim"]  
> and the other one "Jim with black hair" or "Small Jim" or whatever.
>
> <http://en.wikipedia.org/wiki/George_Forman>.
> 

Hello Jan.
Let's clarify a little about this:
1. REST is much more that using HTTP and using Hypermedia as an Engine
to control State. That means, there are several other constrains. The
HyperMedia use is just one of the four constrains needed to achieve the
use of an universal interface.

2. Hypermedia constrain is there because REST was aimed to be a style
for systems in a networked environment whose main interaction is the
transfer of large hypermedia documents.  I had thought always that, if
you are not into that kind of system, you should not use REST as it is,
but you may use a derivative.

3. REST is a style, detailed with the reasoning of each constrain, which
means you can identify which constrains work for your work and use them.
You may be using then a subset of the style, perfectly fine, and fits
with your application. But your application is not, then RESTFull.

4. So, what you see is not only people forgetting about the Hypermedia
constrain, but actually using subsets of the style they need. The name
you suggest to look for is then not related to the lack of Hypermedia
thingies, but of an incomplete use of REST.

Than brings me to the actual problem that faces what you are proposing:
It may be too many names!
Actually, some may be completely new styles aimed to different things.
I can use representational style of resources, without stating the
workflow as a State. It may be transactional and atomic. It may be the
RETA.

Or, we can use the State Machine for workflow, but using RPC as the step
unit.  YOu have SMARPC.

What about the ones that use REST as CRUD, but with resources? CRUDRES
If someone is not using Hypemedias as the state machine supported, it
may be they are not using state machine at all. I have seem apis that
are more like RPC. So, it is Representational, no State, no Transfer,
but RPC. RERPC.

And what if they have state machine workflow on server? No Hypermedia.
That is the tricky one, since the REST name fits, only that it is not
intended for hypermedia transfer, but for transactions. RESTX may be the
name.
etc.

So, and that is something I was planning to mention in a post when
having some time, we may actually review the needs of the applications
and define a style, based on REST, that may fit my app needs, instead of
forcing the app to support REST just to have that name in the credits. 
We may find there are less that a dozen totally different styles, all
REST children, but with a name on their own. With all the rationale on
how to use them, it may be a great help for all those that are not quite
there yet.

William Martinez Pomares.

--- In rest-discuss@yahoogroups.com, Jan Algermissen
<algermissen1971@...> wrote:
>
> Given that the creation of APIs that ignore the hypermedia constraint
is undeniably an ongoing activity wouldn't it be nice to give those a
name in order to differentiate them from RESTful APIs?
>
> I think that it can in various circumstances be argued to be to have
HTTP based APIs that define some URI layout and maybe only use generic
media types. It is certainly more useful than doing the same API with
RMI, SOAP or CORBA.
>
> However, given there is no name for them, they simple become
'REST-APIs' which obfuscates the fact that systems using those APIs will
*not* have the properties induced by REST.
>
> If we name them, differentiation between the two becomes a lot easier.
>
>
> What I lack is a compelling name that sounds cool enough so API owners
can still be proud even if they are not (yet) in the REST-Olymp of
things :-) ?
>
> Any ideas?
>
>
> HTTP-base APIs
> Fixed-URI-APIs
>
> Both *not* cool....
>
> Jan
>
>
>
> -----------------------------------
>  Jan Algermissen, Consultant
>  NORD Software Consulting
>
>  Mail: algermissen@...
>  Blog: http://www.nordsc.com/blog/
>  Work: http://www.nordsc.com/
> -----------------------------------
>

On Feb 18, 2010, at 5:59 PM, William Martinez Pomares wrote:

> Hello Jan.
> Let's clarify a little about this:

Yes, those are valid points.

But aren't there 'REST abuse patterns' that are sufficiently common to warrant to be assigned a name?

Or we call them '!REST'  (not REST) or just HTTP-APIs.

Jan


> 1. REST is much more that using HTTP and using Hypermedia as an Engine
> to control State. That means, there are several other constrains. The
> HyperMedia use is just one of the four constrains needed to achieve the
> use of an universal interface.
> 
> 2. Hypermedia constrain is there because REST was aimed to be a style
> for systems in a networked environment whose main interaction is the
> transfer of large hypermedia documents.  I had thought always that, if
> you are not into that kind of system, you should not use REST as it is,
> but you may use a derivative.
> 
> 3. REST is a style, detailed with the reasoning of each constrain, which
> means you can identify which constrains work for your work and use them.
> You may be using then a subset of the style, perfectly fine, and fits
> with your application. But your application is not, then RESTFull.
> 
> 4. So, what you see is not only people forgetting about the Hypermedia
> constrain, but actually using subsets of the style they need. The name
> you suggest to look for is then not related to the lack of Hypermedia
> thingies, but of an incomplete use of REST.
> 
> Than brings me to the actual problem that faces what you are proposing:
> It may be too many names!
> Actually, some may be completely new styles aimed to different things.
> I can use representational style of resources, without stating the
> workflow as a State. It may be transactional and atomic. It may be the
> RETA.
> 
> Or, we can use the State Machine for workflow, but using RPC as the step
> unit.  YOu have SMARPC.
> 
> What about the ones that use REST as CRUD, but with resources? CRUDRES
> If someone is not using Hypemedias as the state machine supported, it
> may be they are not using state machine at all. I have seem apis that
> are more like RPC. So, it is Representational, no State, no Transfer,
> but RPC. RERPC.
> 
> And what if they have state machine workflow on server? No Hypermedia.
> That is the tricky one, since the REST name fits, only that it is not
> intended for hypermedia transfer, but for transactions. RESTX may be the
> name.
> etc.
> 
> So, and that is something I was planning to mention in a post when
> having some time, we may actually review the needs of the applications
> and define a style, based on REST, that may fit my app needs, instead of
> forcing the app to support REST just to have that name in the credits. 
> We may find there are less that a dozen totally different styles, all
> REST children, but with a name on their own. With all the rationale on
> how to use them, it may be a great help for all those that are not quite
> there yet.
> 
> William Martinez Pomares.
> 
> --- In rest-discuss@yahoogroups.com, Jan Algermissen
> <algermissen1971@...> wrote:
>> 
>> Given that the creation of APIs that ignore the hypermedia constraint
> is undeniably an ongoing activity wouldn't it be nice to give those a
> name in order to differentiate them from RESTful APIs?
>> 
>> I think that it can in various circumstances be argued to be to have
> HTTP based APIs that define some URI layout and maybe only use generic
> media types. It is certainly more useful than doing the same API with
> RMI, SOAP or CORBA.
>> 
>> However, given there is no name for them, they simple become
> 'REST-APIs' which obfuscates the fact that systems using those APIs will
> *not* have the properties induced by REST.
>> 
>> If we name them, differentiation between the two becomes a lot easier.
>> 
>> 
>> What I lack is a compelling name that sounds cool enough so API owners
> can still be proud even if they are not (yet) in the REST-Olymp of
> things :-) ?
>> 
>> Any ideas?
>> 
>> 
>> HTTP-base APIs
>> Fixed-URI-APIs
>> 
>> Both *not* cool....
>> 
>> Jan
>> 
>> 
>> 
>> -----------------------------------
>> Jan Algermissen, Consultant
>> NORD Software Consulting
>> 
>> Mail: algermissen@...
>> Blog: http://www.nordsc.com/blog/
>> Work: http://www.nordsc.com/
>> -----------------------------------
>> 
> 
> 
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Eric J. Bowman wrote:
> I contend that the format of a representation is part of a
> system's hierarchical data.  The proof is right there in curl,
> which sees no hierarchy when it's saving 'resource' and
> 'resource.1' to disk, while obviously recognizing .pdf
> and .html as part of a hierarchy of representations, whether
> by direct dereferencing or by presence in a Content-Location
> response header.

That's an odd way to look at it. The "format of a representation
is part of a system's hierarchical data" if and only if the path
portion of the URI contains information to that effect. If not,
it doesn't. The fact that some domains specifically do this does
not require them all to do so. Curl is suboptimal in this respect
since it does not differentiate responses based on the query
string component.

> But it's still treating URIs opaquely -- links are derived from
> the link relations in the source documents, which are read from
> @href's. There is no analysis of those @href contents by keyword
> or filename extension to determine "resource type".  Clients
> aren't required to know any specifics of a URI's pattern.  That
> would be coupling, which is diametrically opposed to the notion
> of URI opacity in REST.

Absolutely correct. That behavior should be extended to query string
components of the URI as well.

> Don't get carried away by saying that my treating URIs as
> hierarchical or testing whether they have fragments or not,
> amounts to a failure to treat URIs as opaque.  Can you point
> to some constraint in REST that I'm breaking?  Can you find any
> support from Roy to back up this notion that URI opacity means
> that query and filename extension are the same?

Sure. I used to take your position but corrected myself [1] back
in 2005, complete with Fielding quotes and RFC 3986 references ;)

> Are there any
> generic URI parsers you can point me to, which treat query
> strings opaquely?  Or do they all consider '?' to be a reserved
> character?

The '?' character does have a special meaning: it separates the
hierarchical portion of the URI from the opaque part. But the
opaque part is still part of the identifier.

> So the onus is not on me to prove that Roy isn't being clear
> as daylight when he says that "query is not a substitute for
> identification of resources", but on you who think it could
> possibly mean any different to support *your* arguments.  :-)

When I read that statement from Roy [2], I don't see any indication
that it's about "query" as a URI component; instead, it is regarding
"query" as a means of fetching a list of resources. Roy's point
seems to be that returning 38 items in a list within a single
response is no substitute for having distinct URI's for each of
those 38 individual resources.


Robert Brewer
fumanchu@...

[1] http://groups.google.com/group/cherrypy-devel/msg/0fcc62df334bc9ed
[2] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-720

On Thu, Feb 18, 2010 at 2:38 AM, Jan Algermissen <algermissen1971@...>wrote:

>
> On Feb 18, 2010, at 4:15 AM, Guilherme Silveira wrote:
>
> >
> >
> > I'm not sure if design-time, "static hypermedia" makes sense. From the
> message you quoted:
> > Hypermedia means the placement of controls within the
> > presentation of information
> > If the links and controls aren't in the data communicated at runtime,
> then I think it's a stretch to call it "hypermedia".
> > If I got it right, the API in question uses hypermedia to represent state
> transitions that were agreed upon a priori by both server and consumers.
>
> Yes, that is what I mean.
> I know it is not really correct to put it that way, but it occurred to me
> that a description of the available URIs at design time is in some sense
> similar to such a description at run time. It is 'just' the amount of design
> time coupling induced that differs.
>
> Consider WADL at runtime (which is RESTful[1] because you can consider it a
> form) vs. WADL at design time.
>
> If we manage to make designers of 3/4 APIs aware of the coupling they
> introduce and show them the tradeoffs involved, that would be beneficial in
> many ways...
>
>
>
I get what you mean. I was just objecting to the term "static hypermedia".
To me that's confusing because the term "hypermedia" implies controls in
*run-time* data.

We are talking about the system architecture here (which implies run-time
design), not the code constructs -- so the fact that a hypermedia document
was used to say generate code is a different matter.

Andrew


-- 
Andrew Wahbe

> 
> Or we call them '!REST'  (not REST) or just HTTP-APIs.
> 

I would suggest with the volume of email this generates: unREST.

Hi guys,

I'm trying to understand HATEOAS properly and aim to embrace it fully. However, the lack of client side libraries that embrace this is impeding me for the moment. The way I see it, all clients must be only be made known of one URI, say "/". The client then derives the URIs from that link. As such, I was hoping to do something roughly like:

from("/").follow("#users_link").fill_form("search_user", {"id": "someid"}).follow("#user_link").follow("#friends_link")

The goal of the previous command was to get the friends of some user having an ID of 'someid'. It starts by going to the given URL, then from the page it got, follows a certain link which redirect it to the resource for a list of users. It then searches for the user, probably filling up a form, submits it, and goes to the user's page. From the user's page, there is a link to the friends page, and that is followed and eventually processed.

In reality of course, this shouldn't really necessitate multiple calls to the server if called multiple times since previous results have been cached and processed on the client side. Only when the cache expires, should there be an attempt to request again. I'm not really sure if RESTful clients that respect HATEOAS do it this way, and should they in the first place. If they do, are there tools that exist for this?

On a side note, content type negotiation should be preconfigured before doing the call I stated above.

Thanks,

Jan Vincent Liwanag
jvliwanag@...

Comments Below...

--- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
>
> 
> On Feb 18, 2010, at 5:59 PM, William Martinez Pomares wrote:
> 
> > Hello Jan.
> > Let's clarify a little about this:
> 
> Yes, those are valid points.
> 
> But aren't there 'REST abuse patterns' that are sufficiently common to warrant to be assigned a name?
> 
> Or we call them '!REST'  (not REST) or just HTTP-APIs.
> 
> Jan
> 
> 

Totally agree. 

But one thing is a REST Abuse pattern, and another one is a new style that is so similar, but not the same, as REST. Should not have reference to REST name, but should have a name, and not only that, also a definition of constrains, the goal or target, the consequences, etc. Just like documenting a new style. 

BTW, one thing is a style and another one an API. Style is more like a pattern, thus should have a name for many APIs. So, REST is an architectural style, thus created to guide the creation of systems, not APIs. An API is, as the name indicates, an interface to communicate with an application or system behind. It makes sense the application is RESTFull, but more than often, the application is a SOA or a plain distributed object oriented one, that someone wants to expose to the web. I see not REST anywhere there. 

Cheers
William. 

Funny, now that I am understanding what Jan and others are saying about HATEOAS, REST and why so many "rest" apis are not truly REST, I too think we need some sort of new API name for the "almost REST but not quite" HTTP api format many of us are using. It's basically a better/easier XML-RPC and Web Services.. while almost being rest as well.

--- On Thu, 2/18/10, William Martinez Pomares <wmartinez@...> wrote:

From: William Martinez Pomares <wmartinez@...>
Subject: [rest-discuss] Re: A Name for "3 out of 4 REST constraints" APIs?
To: rest-discuss@yahoogroups.com
Date: Thursday, February 18, 2010, 7:14 PM















 
 



  


    
      
      
      Comments Below...



--- In rest-discuss@ yahoogroups. com, Jan Algermissen <algermissen1971@ ...> wrote:

>

> 

> On Feb 18, 2010, at 5:59 PM, William Martinez Pomares wrote:

> 

> > Hello Jan.

> > Let's clarify a little about this:

> 

> Yes, those are valid points.

> 

> But aren't there 'REST abuse patterns' that are sufficiently common to warrant to be assigned a name?

> 

> Or we call them '!REST'  (not REST) or just HTTP-APIs.

> 

> Jan

> 

> 



Totally agree. 



But one thing is a REST Abuse pattern, and another one is a new style that is so similar, but not the same, as REST. Should not have reference to REST name, but should have a name, and not only that, also a definition of constrains, the goal or target, the consequences, etc. Just like documenting a new style. 



BTW, one thing is a style and another one an API. Style is more like a pattern, thus should have a name for many APIs. So, REST is an architectural style, thus created to guide the creation of systems, not APIs. An API is, as the name indicates, an interface to communicate with an application or system behind. It makes sense the application is RESTFull, but more than often, the application is a SOA or a plain distributed object oriented one, that someone wants to expose to the web. I see not REST anywhere there. 



Cheers

William. 





    
     

    
    


 



  











      

I think one problem you may run in to in order to be truly RESTful, is assuming that the response will return the link you wish to follow. From your multiple method invocation (assuming I am reading that correctly that it is one line of code with multiple method calls), the 2nd method invocation assumes the link is part of the response. What happens if it's not? For what ever reason the server decided not to include it, be it an error, invalid authorization, etc?

--- On Thu, 2/18/10, Jan Vincent <jvliwanag@...> wrote:

From: Jan Vincent <jvliwanag@...>
Subject: [rest-discuss] HATEOAS and Cache
To: rest-discuss@yahoogroups.com
Date: Thursday, February 18, 2010, 4:56 PM















 
 



  


    
      
      
      Hi guys,



I'm trying to understand HATEOAS properly and aim to embrace it fully. However, the lack of client side libraries that embrace this is impeding me for the moment. The way I see it, all clients must be only be made known of one URI, say "/". The client then derives the URIs from that link. As such, I was hoping to do something roughly like:



from("/").follow( "#users_link" ).fill_form( "search_user" , {"id": "someid"}).follow( "#user_link" ).follow( "#friends_ link")



The goal of the previous command was to get the friends of some user having an ID of 'someid'. It starts by going to the given URL, then from the page it got, follows a certain link which redirect it to the resource for a list of users. It then searches for the user, probably filling up a form, submits it, and goes to the user's page. From the user's page, there is a link to the friends page, and that is followed and eventually processed.



In reality of course, this shouldn't really necessitate multiple calls to the server if called multiple times since previous results have been cached and processed on the client side. Only when the cache expires, should there be an attempt to request again. I'm not really sure if RESTful clients that respect HATEOAS do it this way, and should they in the first place. If they do, are there tools that exist for this?



On a side note, content type negotiation should be preconfigured before doing the call I stated above.



Thanks,



Jan Vincent Liwanag

jvliwanag@gmail. com





    
     

    
    


 



  











      

On Feb 19, 2010, at 7:45 AM, Kevin Duffey wrote:

> 
> 
> I think one problem you may run in to in order to be truly RESTful, is assuming that the response will return the link you wish to follow. From your multiple method invocation (assuming I am reading that correctly that it is one line of code with multiple method calls), the 2nd method invocation assumes the link is part of the response. What happens if it's not?


Exactly.

This is why hiding a state traversal behind an OO interface violates the hypermedia constraint[1]. It hides the fact that the client should accept the case of the link not being present as part of normal communication. That is: not throw an exception as the default behaviour.

Jan




[1] Unless you have a media type that mandates the link to be there in valid instances, e.g.

GET /sth
Accept: appliation/foo

200 Ok
Content-Type: appliation/foo

<foo href=""/>

If vaid foo messages MUST contain the href attr then you could hide this in an OO call. But few media types ever do this and it can IMHO be considered bad media type design.


> For what ever reason the server decided not to include it, be it an error, invalid authorization, etc?
> 
> 
> --- On Thu, 2/18/10, Jan Vincent <jvliwanag@...> wrote:
> 
> From: Jan Vincent <jvliwanag@...>
> Subject: [rest-discuss] HATEOAS and Cache
> To: rest-discuss@yahoogroups.com
> Date: Thursday, February 18, 2010, 4:56 PM
> 
> Hi guys,
> 
> I'm trying to understand HATEOAS properly and aim to embrace it fully. However, the lack of client side libraries that embrace this is impeding me for the moment. The way I see it, all clients must be only be made known of one URI, say "/". The client then derives the URIs from that link. As such, I was hoping to do something roughly like:
> 
> from("/").follow( "#users_link" ).fill_form( "search_user" , {"id": "someid"}).follow( "#user_link" ).follow( "#friends_ link")
> 
> The goal of the previous command was to get the friends of some user having an ID of 'someid'. It starts by going to the given URL, then from the page it got, follows a certain link which redirect it to the resource for a list of users. It then searches for the user, probably filling up a form, submits it, and goes to the user's page. From the user's page, there is a link to the friends page, and that is followed and eventually processed.
> 
> In reality of course, this shouldn't really necessitate multiple calls to the server if called multiple times since previous results have been cached and processed on the client side. Only when the cache expires, should there be an attempt to request again. I'm not really sure if RESTful clients that respect HATEOAS do it this way, and should they in the first place. If they do, are there tools that exist for this?
> 
> On a side note, content type negotiation should be preconfigured before doing the call I stated above.
> 
> Thanks,
> 
> Jan Vincent Liwanag
> jvliwanag@gmail. com
> 
> 
> 
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

On Feb 19, 2010, at 1:56 AM, Jan Vincent wrote:

> Hi guys,
> 
> I'm trying to understand HATEOAS properly and aim to embrace it fully. However, the lack of client side libraries that embrace this is impeding me for the moment. The way I see it, all clients must be only be made known of one URI, say "/". The client then derives the URIs from that link. As such, I was hoping to do something roughly like:
> 
> from("/").follow("#users_link").fill_form("search_user", {"id": "someid"}).follow("#user_link").follow("#friends_link")
> 
> The goal of the previous command was to get the friends of some user having an ID of 'someid'. It starts by going to the given URL, then from the page it got, follows a certain link which redirect it to the resource for a list of users. It then searches for the user, probably filling up a form, submits it, and goes to the user's page. From the user's page, there is a link to the friends page, and that is followed and eventually processed.

This is not a RESTful client implementation because it is based on expectations about the application's state machine and the client cannot have such expectations. The server might change the whole state machine at runtime which is not an error condition but a feature of REST.

Think this instead:

The client has an overall goal (unless it is a robot) and must for each steady state it is being put in by the server understand how to proceed achieving that goal.

If the client knows that the server uses media types A, B and C[1] it must handle A, B and C for any steady state it reaches.

Jan



[1] In my opinion, the client must know the types at design time - otherwise, the client could not be coded in the first place


> 
> In reality of course, this shouldn't really necessitate multiple calls to the server if called multiple times since previous results have been cached and processed on the client side. Only when the cache expires, should there be an attempt to request again. I'm not really sure if RESTful clients that respect HATEOAS do it this way, and should they in the first place. If they do, are there tools that exist for this?
> 
> On a side note, content type negotiation should be preconfigured before doing the call I stated above.
> 
> Thanks,
> 
> Jan Vincent Liwanag
> jvliwanag@...
> 
> 
> 
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

On Feb 19, 2010, at 8:03 AM, Jan Algermissen wrote:

> 
> [1] In my opinion, the client must know the types at design time - otherwise, the client could not be coded in the first place

Meant to add this link to some thoughts about this: http://www.nordsc.com/blog/?cat=4

Jan


> 
> 
>> 
>> In reality of course, this shouldn't really necessitate multiple calls to the server if called multiple times since previous results have been cached and processed on the client side. Only when the cache expires, should there be an attempt to request again. I'm not really sure if RESTful clients that respect HATEOAS do it this way, and should they in the first place. If they do, are there tools that exist for this?
>> 
>> On a side note, content type negotiation should be preconfigured before doing the call I stated above.
>> 
>> Thanks,
>> 
>> Jan Vincent Liwanag
>> jvliwanag@...
>> 
>> 
>> 
>> 
>> 
>> ------------------------------------
>> 
>> Yahoo! Groups Links
>> 
>> 
>> 
> 
> -----------------------------------
> Jan Algermissen, Consultant
> NORD Software Consulting
> 
> Mail: algermissen@...
> Blog: http://www.nordsc.com/blog/
> Work: http://www.nordsc.com/
> -----------------------------------
> 
> 
> 
> 
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

True enough,

Doing:

> from("/").follow( "#users_link" ).fill_form( "search_user" , {"id": "someid"}).follow( "#user_link" ).follow( "#friends_ link")


Doesn't cut it since it assumes specific responses from the server. But the point of HATEOAS I believe is that links are indeed provided for me to traverse through. I may instead represent this as some form of tree, perhaps something like:

from("/").follow("#users_link" ).handle({
  200: fill_form("search_user" , ...)...
  404: ...
})

On the other hand, I would rather do the previous one and handle exceptions instead. The client should know some information about the server's state machine right? And if it asks right, it should rightfully expect that it gets the content-type it requested for. How else would it be able to do its task?

On Feb 19, 2010, at 3:05 PM, Jan Algermissen wrote:

> 
> On Feb 19, 2010, at 8:03 AM, Jan Algermissen wrote:
> 
>> 
>> [1] In my opinion, the client must know the types at design time - otherwise, the client could not be coded in the first place
> 
> Meant to add this link to some thoughts about this: http://www.nordsc.com/blog/?cat=4
> 
> Jan
> 
> 
>> 
>> 
>>> 
>>> In reality of course, this shouldn't really necessitate multiple calls to the server if called multiple times since previous results have been cached and processed on the client side. Only when the cache expires, should there be an attempt to request again. I'm not really sure if RESTful clients that respect HATEOAS do it this way, and should they in the first place. If they do, are there tools that exist for this?
>>> 
>>> On a side note, content type negotiation should be preconfigured before doing the call I stated above.
>>> 
>>> Thanks,
>>> 
>>> Jan Vincent Liwanag
>>> jvliwanag@...
>>> 
>>> 
>>> 
>>> 
>>> 
>>> ------------------------------------
>>> 
>>> Yahoo! Groups Links
>>> 
>>> 
>>> 
>> 
>> -----------------------------------
>> Jan Algermissen, Consultant
>> NORD Software Consulting
>> 
>> Mail: algermissen@...
>> Blog: http://www.nordsc.com/blog/
>> Work: http://www.nordsc.com/
>> -----------------------------------
>> 
>> 
>> 
>> 
>> 
>> 
>> ------------------------------------
>> 
>> Yahoo! Groups Links
>> 
>> 
>> 
> 
> -----------------------------------
> Jan Algermissen, Consultant
> NORD Software Consulting
> 
> Mail: algermissen@...
> Blog: http://www.nordsc.com/blog/
> Work: http://www.nordsc.com/
> -----------------------------------
> 
> 
> 
> 

Jan Vincent Liwanag
jvliwanag@...

On Feb 19, 2010, at 8:19 AM, Jan Vincent wrote:

> True enough,
> 
> Doing:
> 
>> from("/").follow( "#users_link" ).fill_form( "search_user" , {"id": "someid"}).follow( "#user_link" ).follow( "#friends_ link")
> 
> Doesn't cut it since it assumes specific responses from the server. But the point of HATEOAS I believe is that links are indeed provided for me to traverse through.

Yes, but you can make no assumption
a) about the media type returned
b) about what links, forms etc. you will find in there

> I may instead represent this as some form of tree, perhaps something like:
> 
> from("/").follow("#users_link" ).handle({
>   200: fill_form("search_user" , ...)...
>   404: ...
> })

The 200 still does not mean that the form will be there (or that the response will be in a media type that you expect)
Also, what about 201,202,303,204.... you have to handle all of those, too. ... yes, the REST client side is hard ...


> 
> On the other hand, I would rather do the previous one and handle exceptions instead.

Well, you can, of course. But you must understand that what you handle as exceptions does not mean the server behaves incorrect because any valid HTTP response is part of the contract. The exceptions would essentially only handle the client side 'broken' implementation.

> The client should know some information about the server's state machine right?

No! That is the essence of the hypermedia constraint. It must look at each steady state in isolation and 'make the best of it' in a sense.

Note that this influences the issue of media type design substantially because you can design types that make this very hard or types that makethis easier.

> And if it asks right, it should rightfully expect that it gets the content-type it requested for.

Still, if it gets a 406 it should be able to handle that and not just dump an exception into the logs.

> How else would it be able to do its task?

By knowing the set of media types to expect and by handling every media type for every response.


Jan

> 
> On Feb 19, 2010, at 3:05 PM, Jan Algermissen wrote:
> 
>> 
>> On Feb 19, 2010, at 8:03 AM, Jan Algermissen wrote:
>> 
>>> 
>>> [1] In my opinion, the client must know the types at design time - otherwise, the client could not be coded in the first place
>> 
>> Meant to add this link to some thoughts about this: http://www.nordsc.com/blog/?cat=4
>> 
>> Jan
>> 
>> 
>>> 
>>> 
>>>> 
>>>> In reality of course, this shouldn't really necessitate multiple calls to the server if called multiple times since previous results have been cached and processed on the client side. Only when the cache expires, should there be an attempt to request again. I'm not really sure if RESTful clients that respect HATEOAS do it this way, and should they in the first place. If they do, are there tools that exist for this?
>>>> 
>>>> On a side note, content type negotiation should be preconfigured before doing the call I stated above.
>>>> 
>>>> Thanks,
>>>> 
>>>> Jan Vincent Liwanag
>>>> jvliwanag@...
>>>> 
>>>> 
>>>> 
>>>> 
>>>> 
>>>> ------------------------------------
>>>> 
>>>> Yahoo! Groups Links
>>>> 
>>>> 
>>>> 
>>> 
>>> -----------------------------------
>>> Jan Algermissen, Consultant
>>> NORD Software Consulting
>>> 
>>> Mail: algermissen@...
>>> Blog: http://www.nordsc.com/blog/
>>> Work: http://www.nordsc.com/
>>> -----------------------------------
>>> 
>>> 
>>> 
>>> 
>>> 
>>> 
>>> ------------------------------------
>>> 
>>> Yahoo! Groups Links
>>> 
>>> 
>>> 
>> 
>> -----------------------------------
>> Jan Algermissen, Consultant
>> NORD Software Consulting
>> 
>> Mail: algermissen@...
>> Blog: http://www.nordsc.com/blog/
>> Work: http://www.nordsc.com/
>> -----------------------------------
>> 
>> 
>> 
>> 
> 
> Jan Vincent Liwanag
> jvliwanag@...
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

On Feb 19, 2010, at 3:36 PM, Jan Algermissen wrote:

> 
> On Feb 19, 2010, at 8:19 AM, Jan Vincent wrote:
> 
>> True enough,
>> 
>> Doing:
>> 
>>> from("/").follow( "#users_link" ).fill_form( "search_user" , {"id": "someid"}).follow( "#user_link" ).follow( "#friends_ link")
>> 
>> Doesn't cut it since it assumes specific responses from the server. But the point of HATEOAS I believe is that links are indeed provided for me to traverse through.
> 
> Yes, but you can make no assumption
> a) about the media type returned
> b) about what links, forms etc. you will find in there

Can't I? If the server acts right, it should recognize my Accept header. If it doesn't have the Content-Type that I recognize, then my client gives up. It simply doesn't know how to understand the new Content-Type. Since the client is preprogrammed, it's one limitation I should live with.

> 
>> I may instead represent this as some form of tree, perhaps something like:
>> 
>> from("/").follow("#users_link" ).handle({
>>  200: fill_form("search_user" , ...)...
>>  404: ...
>> })
> 
> The 200 still does not mean that the form will be there (or that the response will be in a media type that you expect)
> Also, what about 201,202,303,204.... you have to handle all of those, too. ... yes, the REST client side is hard ...
> 
If I do a GET, i should expect a 200 if it exists, 404 otherwise. I can choose logical defaults for 3xx series possibly make it transparent to the programmer unless he chooses to do so. 5xx series, well, that would raise exception. Same with PUT, POST, etc, there are certain status codes the client should expect, some status codes wherein default action would be ok, and the rest, that simply won't make sense (i.e., a 201 on a GET request).
> 
>> 
>> On the other hand, I would rather do the previous one and handle exceptions instead.
> 
> Well, you can, of course. But you must understand that what you handle as exceptions does not mean the server behaves incorrect because any valid HTTP response is part of the contract. The exceptions would essentially only handle the client side 'broken' implementation.
> 
>> The client should know some information about the server's state machine right?
> 
> No! That is the essence of the hypermedia constraint. It must look at each steady state in isolation and 'make the best of it' in a sense.
> 
> Note that this influences the issue of media type design substantially because you can design types that make this very hard or types that makethis easier.

It doesn't have to learn of the entire server's state machine, but just enough of it. The clients need some prior knowledge on how to jump from one resource to another, possibly in the form of xpath, json traversal rules, or rdf relationships.

> 
>> And if it asks right, it should rightfully expect that it gets the content-type it requested for.
> 
> Still, if it gets a 406 it should be able to handle that and not just dump an exception into the logs.

What else is there to do? Unless some AI stuff is going on, I don't think it can do much to recover.

> 
>> How else would it be able to do its task?
> 
> By knowing the set of media types to expect and by handling every media type for every response.

Exactly. There are some assumptions that must be in place -- certain expectations how the server can act.

I'm curious though. Say for a social network API, how would some client know who the friends are of some user?

> 
> 
> Jan
> 
>> 
>> On Feb 19, 2010, at 3:05 PM, Jan Algermissen wrote:
>> 
>>> 
>>> On Feb 19, 2010, at 8:03 AM, Jan Algermissen wrote:
>>> 
>>>> 
>>>> [1] In my opinion, the client must know the types at design time - otherwise, the client could not be coded in the first place
>>> 
>>> Meant to add this link to some thoughts about this: http://www.nordsc.com/blog/?cat=4
>>> 
>>> Jan
>>> 
>>> 
>>>> 
>>>> 
>>>>> 
>>>>> In reality of course, this shouldn't really necessitate multiple calls to the server if called multiple times since previous results have been cached and processed on the client side. Only when the cache expires, should there be an attempt to request again. I'm not really sure if RESTful clients that respect HATEOAS do it this way, and should they in the first place. If they do, are there tools that exist for this?
>>>>> 
>>>>> On a side note, content type negotiation should be preconfigured before doing the call I stated above.
>>>>> 
>>>>> Thanks,
>>>>> 
>>>>> Jan Vincent Liwanag
>>>>> jvliwanag@...
>>>>> 
>>>>> 
>>>>> 
>>>>> 
>>>>> 
>>>>> ------------------------------------
>>>>> 
>>>>> Yahoo! Groups Links
>>>>> 
>>>>> 
>>>>> 
>>>> 
>>>> -----------------------------------
>>>> Jan Algermissen, Consultant
>>>> NORD Software Consulting
>>>> 
>>>> Mail: algermissen@...
>>>> Blog: http://www.nordsc.com/blog/
>>>> Work: http://www.nordsc.com/
>>>> -----------------------------------
>>>> 
>>>> 
>>>> 
>>>> 
>>>> 
>>>> 
>>>> ------------------------------------
>>>> 
>>>> Yahoo! Groups Links
>>>> 
>>>> 
>>>> 
>>> 
>>> -----------------------------------
>>> Jan Algermissen, Consultant
>>> NORD Software Consulting
>>> 
>>> Mail: algermissen@...
>>> Blog: http://www.nordsc.com/blog/
>>> Work: http://www.nordsc.com/
>>> -----------------------------------
>>> 
>>> 
>>> 
>>> 
>> 
>> Jan Vincent Liwanag
>> jvliwanag@gmail.com
>> 
>> 
>> 
> 
> -----------------------------------
> Jan Algermissen, Consultant
> NORD Software Consulting
> 
> Mail: algermissen@...
> Blog: http://www.nordsc.com/blog/
> Work: http://www.nordsc.com/
> -----------------------------------
> 
> 
> 
> 

Jan Vincent Liwanag
jvliwanag@gmail.com

On Feb 19, 2010, at 9:02 AM, Jan Vincent wrote:

> 
> On Feb 19, 2010, at 3:36 PM, Jan Algermissen wrote:
> 
>> 
>> On Feb 19, 2010, at 8:19 AM, Jan Vincent wrote:
>> 
>>> True enough,
>>> 
>>> Doing:
>>> 
>>>> from("/").follow( "#users_link" ).fill_form( "search_user" , {"id": "someid"}).follow( "#user_link" ).follow( "#friends_ link")
>>> 
>>> Doesn't cut it since it assumes specific responses from the server. But the point of HATEOAS I believe is that links are indeed provided for me to traverse through.
>> 
>> Yes, but you can make no assumption
>> a) about the media type returned
>> b) about what links, forms etc. you will find in there
> 
> Can't I? If the server acts right, it should recognize my Accept header.

There might be several types you put in the accept header. The client should handle any matching response.

> If it doesn't have the Content-Type that I recognize, then my client gives up. It simply doesn't know how to understand the new Content-Type. Since the client is preprogrammed, it's one limitation I should live with.

Yes. However, I like to emphasize that with REST it des not stop there because you do not just have 'broken communication' but in fact still an ongoing communication (a benefit of uniform status codes) and it makes sense to think about leveraging that situation. You could, for example, have the client open an RFC ticket in some helpdesk system to trigger an ASAP update of the client capabilities. I consider that different from dumping a stack trace in the logs and calling a developer with 'uhh - something is wrong'.

Technically, yes - at some point you just need to give up.

> 
>> 
>>> I may instead represent this as some form of tree, perhaps something like:
>>> 
>>> from("/").follow("#users_link" ).handle({
>>> 200: fill_form("search_user" , ...)...
>>> 404: ...
>>> })
>> 
>> The 200 still does not mean that the form will be there (or that the response will be in a media type that you expect)
>> Also, what about 201,202,303,204.... you have to handle all of those, too. ... yes, the REST client side is hard ...
>> 
> If I do a GET, i should expect a 200 if it exists, 404 otherwise. I can choose logical defaults for 3xx series possibly make it transparent to the programmer unless he chooses to do so. 5xx series, well, that would raise exception. Same with PUT, POST, etc, there are certain status codes the client should expect, some status codes wherein default action would be ok, and the rest, that simply won't make sense (i.e., a 201 on a GET request).

Yes. I wanted to stress the point that you should handle those codes that make sense (202 on GET also, IMO). But as long as you think along the lines you describe that's ok I guess.


>> 
>>> 
>>> On the other hand, I would rather do the previous one and handle exceptions instead.
>> 
>> Well, you can, of course. But you must understand that what you handle as exceptions does not mean the server behaves incorrect because any valid HTTP response is part of the contract. The exceptions would essentially only handle the client side 'broken' implementation.
>> 
>>> The client should know some information about the server's state machine right?
>> 
>> No! That is the essence of the hypermedia constraint. It must look at each steady state in isolation and 'make the best of it' in a sense.
>> 
>> Note that this influences the issue of media type design substantially because you can design types that make this very hard or types that makethis easier.
> 
> It doesn't have to learn of the entire server's state machine, but just enough of it. The clients need some prior knowledge on how to jump from one resource to another,

It must know the media type to understand the meaning of the current transitions. It can then coose the transition that advances its built-in goal but it cannot have any expectation about what is being returned by the server.

(Note that the client *can* expect for the server to not lie, e.g. <img src=""/> must point to an image, <app:collection href=""/> must point to a collection.)


> possibly in the form of xpath, json traversal rules, or rdf relationships.

What do you mean here? I did not get that.



> 
>> 
>>> And if it asks right, it should rightfully expect that it gets the content-type it requested for.
>> 
>> Still, if it gets a 406 it should be able to handle that and not just dump an exception into the logs.
> 
> What else is there to do? Unless some AI stuff is going on, I don't think it can do much to recover.

See above: leverage the still existing conversation. In addition, think more in terms of 'client is not able to reach its overall goal' from the current steady state as opposed to 'the server did not send me what it should have - that's an exception'. Even if the end result is about the same - the style inthinging is different.


> 
>> 
>>> How else would it be able to do its task?
>> 
>> By knowing the set of media types to expect and by handling every media type for every response.
> 
> Exactly. There are some assumptions that must be in place -- certain expectations how the server can act.
> 
> I'm curious though. Say for a social network API, how would some client know who the friends are of some user?

What do you mean?


Jan



> 
>> 
>> 
>> Jan
>> 
>>> 
>>> On Feb 19, 2010, at 3:05 PM, Jan Algermissen wrote:
>>> 
>>>> 
>>>> On Feb 19, 2010, at 8:03 AM, Jan Algermissen wrote:
>>>> 
>>>>> 
>>>>> [1] In my opinion, the client must know the types at design time - otherwise, the client could not be coded in the first place
>>>> 
>>>> Meant to add this link to some thoughts about this: http://www.nordsc.com/blog/?cat=4
>>>> 
>>>> Jan
>>>> 
>>>> 
>>>>> 
>>>>> 
>>>>>> 
>>>>>> In reality of course, this shouldn't really necessitate multiple calls to the server if called multiple times since previous results have been cached and processed on the client side. Only when the cache expires, should there be an attempt to request again. I'm not really sure if RESTful clients that respect HATEOAS do it this way, and should they in the first place. If they do, are there tools that exist for this?
>>>>>> 
>>>>>> On a side note, content type negotiation should be preconfigured before doing the call I stated above.
>>>>>> 
>>>>>> Thanks,
>>>>>> 
>>>>>> Jan Vincent Liwanag
>>>>>> jvliwanag@...
>>>>>> 
>>>>>> 
>>>>>> 
>>>>>> 
>>>>>> 
>>>>>> ------------------------------------
>>>>>> 
>>>>>> Yahoo! Groups Links
>>>>>> 
>>>>>> 
>>>>>> 
>>>>> 
>>>>> -----------------------------------
>>>>> Jan Algermissen, Consultant
>>>>> NORD Software Consulting
>>>>> 
>>>>> Mail: algermissen@...
>>>>> Blog: http://www.nordsc.com/blog/
>>>>> Work: http://www.nordsc.com/
>>>>> -----------------------------------
>>>>> 
>>>>> 
>>>>> 
>>>>> 
>>>>> 
>>>>> 
>>>>> ------------------------------------
>>>>> 
>>>>> Yahoo! Groups Links
>>>>> 
>>>>> 
>>>>> 
>>>> 
>>>> -----------------------------------
>>>> Jan Algermissen, Consultant
>>>> NORD Software Consulting
>>>> 
>>>> Mail: algermissen@...
>>>> Blog: http://www.nordsc.com/blog/
>>>> Work: http://www.nordsc.com/
>>>> -----------------------------------
>>>> 
>>>> 
>>>> 
>>>> 
>>> 
>>> Jan Vincent Liwanag
>>> jvliwanag@...
>>> 
>>> 
>>> 
>> 
>> -----------------------------------
>> Jan Algermissen, Consultant
>> NORD Software Consulting
>> 
>> Mail: algermissen@...
>> Blog: http://www.nordsc.com/blog/
>> Work: http://www.nordsc.com/
>> -----------------------------------
>> 
>> 
>> 
>> 
> 
> Jan Vincent Liwanag
> jvliwanag@...
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

First off,

Thanks for the insights. Perhaps my POV on HATEOAS still needs tweaking. Let's have some theoretical desktop client for a social network such as facebook. The desktop client say, simply needs to display the friends of some user. Now, the social network published it's API and the resources that can be accessed. Say, there are three of them

Root Resource ("/") - The only one that has a URL, and contains links to other resources, for simplicity, say this contains all the links to all its users.
User Resource - Give some info about the user, and more importantly, it has the link to the Friends Resource of the User
Friends Resource - Contains the list of friends, and the links to their respective User Resources

If the desktop client aims to accomplish what it's supposed to, I aim to expose two methods to be used by the application, say:

get_user_info(User)
get_friends(User)

Internally, it traverses from the root until it ends up getting the information it needs.

If I get what you're saying though, I probably shouldn't even expose those two methods? Am I thinking about this all wrong?

On Feb 19, 2010, at 4:18 PM, Jan Algermissen wrote:

> 
> On Feb 19, 2010, at 9:02 AM, Jan Vincent wrote:
> 
>> 
>> On Feb 19, 2010, at 3:36 PM, Jan Algermissen wrote:
>> 
>>> 
>>> On Feb 19, 2010, at 8:19 AM, Jan Vincent wrote:
>>> 
>>>> True enough,
>>>> 
>>>> Doing:
>>>> 
>>>>> from("/").follow( "#users_link" ).fill_form( "search_user" , {"id": "someid"}).follow( "#user_link" ).follow( "#friends_ link")
>>>> 
>>>> Doesn't cut it since it assumes specific responses from the server. But the point of HATEOAS I believe is that links are indeed provided for me to traverse through.
>>> 
>>> Yes, but you can make no assumption
>>> a) about the media type returned
>>> b) about what links, forms etc. you will find in there
>> 
>> Can't I? If the server acts right, it should recognize my Accept header.
> 
> There might be several types you put in the accept header. The client should handle any matching response.
> 
>> If it doesn't have the Content-Type that I recognize, then my client gives up. It simply doesn't know how to understand the new Content-Type. Since the client is preprogrammed, it's one limitation I should live with.
> 
> Yes. However, I like to emphasize that with REST it des not stop there because you do not just have 'broken communication' but in fact still an ongoing communication (a benefit of uniform status codes) and it makes sense to think about leveraging that situation. You could, for example, have the client open an RFC ticket in some helpdesk system to trigger an ASAP update of the client capabilities. I consider that different from dumping a stack trace in the logs and calling a developer with 'uhh - something is wrong'.
> 
> Technically, yes - at some point you just need to give up.
> 
>> 
>>> 
>>>> I may instead represent this as some form of tree, perhaps something like:
>>>> 
>>>> from("/").follow("#users_link" ).handle({
>>>> 200: fill_form("search_user" , ...)...
>>>> 404: ...
>>>> })
>>> 
>>> The 200 still does not mean that the form will be there (or that the response will be in a media type that you expect)
>>> Also, what about 201,202,303,204.... you have to handle all of those, too. ... yes, the REST client side is hard ...
>>> 
>> If I do a GET, i should expect a 200 if it exists, 404 otherwise. I can choose logical defaults for 3xx series possibly make it transparent to the programmer unless he chooses to do so. 5xx series, well, that would raise exception. Same with PUT, POST, etc, there are certain status codes the client should expect, some status codes wherein default action would be ok, and the rest, that simply won't make sense (i.e., a 201 on a GET request).
> 
> Yes. I wanted to stress the point that you should handle those codes that make sense (202 on GET also, IMO). But as long as you think along the lines you describe that's ok I guess.
> 
> 
>>> 
>>>> 
>>>> On the other hand, I would rather do the previous one and handle exceptions instead.
>>> 
>>> Well, you can, of course. But you must understand that what you handle as exceptions does not mean the server behaves incorrect because any valid HTTP response is part of the contract. The exceptions would essentially only handle the client side 'broken' implementation.
>>> 
>>>> The client should know some information about the server's state machine right?
>>> 
>>> No! That is the essence of the hypermedia constraint. It must look at each steady state in isolation and 'make the best of it' in a sense.
>>> 
>>> Note that this influences the issue of media type design substantially because you can design types that make this very hard or types that makethis easier.
>> 
>> It doesn't have to learn of the entire server's state machine, but just enough of it. The clients need some prior knowledge on how to jump from one resource to another,
> 
> It must know the media type to understand the meaning of the current transitions. It can then coose the transition that advances its built-in goal but it cannot have any expectation about what is being returned by the server.
> 
> (Note that the client *can* expect for the server to not lie, e.g. <img src=""/> must point to an image, <app:collection href=""/> must point to a collection.)
> 
> 
>> possibly in the form of xpath, json traversal rules, or rdf relationships.
> 
> What do you mean here? I did not get that.
> 
> 
> 
>> 
>>> 
>>>> And if it asks right, it should rightfully expect that it gets the content-type it requested for.
>>> 
>>> Still, if it gets a 406 it should be able to handle that and not just dump an exception into the logs.
>> 
>> What else is there to do? Unless some AI stuff is going on, I don't think it can do much to recover.
> 
> See above: leverage the still existing conversation. In addition, think more in terms of 'client is not able to reach its overall goal' from the current steady state as opposed to 'the server did not send me what it should have - that's an exception'. Even if the end result is about the same - the style inthinging is different.
> 
> 
>> 
>>> 
>>>> How else would it be able to do its task?
>>> 
>>> By knowing the set of media types to expect and by handling every media type for every response.
>> 
>> Exactly. There are some assumptions that must be in place -- certain expectations how the server can act.
>> 
>> I'm curious though. Say for a social network API, how would some client know who the friends are of some user?
> 
> What do you mean?
> 
> 
> Jan
> 
> 
> 
>> 
>>> 
>>> 
>>> Jan
>>> 
>>>> 
>>>> On Feb 19, 2010, at 3:05 PM, Jan Algermissen wrote:
>>>> 
>>>>> 
>>>>> On Feb 19, 2010, at 8:03 AM, Jan Algermissen wrote:
>>>>> 
>>>>>> 
>>>>>> [1] In my opinion, the client must know the types at design time - otherwise, the client could not be coded in the first place
>>>>> 
>>>>> Meant to add this link to some thoughts about this: http://www.nordsc.com/blog/?cat=4
>>>>> 
>>>>> Jan
>>>>> 
>>>>> 
>>>>>> 
>>>>>> 
>>>>>>> 
>>>>>>> In reality of course, this shouldn't really necessitate multiple calls to the server if called multiple times since previous results have been cached and processed on the client side. Only when the cache expires, should there be an attempt to request again. I'm not really sure if RESTful clients that respect HATEOAS do it this way, and should they in the first place. If they do, are there tools that exist for this?
>>>>>>> 
>>>>>>> On a side note, content type negotiation should be preconfigured before doing the call I stated above.
>>>>>>> 
>>>>>>> Thanks,
>>>>>>> 
>>>>>>> Jan Vincent Liwanag
>>>>>>> jvliwanag@...
>>>>>>> 
>>>>>>> 
>>>>>>> 
>>>>>>> 
>>>>>>> 
>>>>>>> ------------------------------------
>>>>>>> 
>>>>>>> Yahoo! Groups Links
>>>>>>> 
>>>>>>> 
>>>>>>> 
>>>>>> 
>>>>>> -----------------------------------
>>>>>> Jan Algermissen, Consultant
>>>>>> NORD Software Consulting
>>>>>> 
>>>>>> Mail: algermissen@...
>>>>>> Blog: http://www.nordsc.com/blog/
>>>>>> Work: http://www.nordsc.com/
>>>>>> -----------------------------------
>>>>>> 
>>>>>> 
>>>>>> 
>>>>>> 
>>>>>> 
>>>>>> 
>>>>>> ------------------------------------
>>>>>> 
>>>>>> Yahoo! Groups Links
>>>>>> 
>>>>>> 
>>>>>> 
>>>>> 
>>>>> -----------------------------------
>>>>> Jan Algermissen, Consultant
>>>>> NORD Software Consulting
>>>>> 
>>>>> Mail: algermissen@acm.org
>>>>> Blog: http://www.nordsc.com/blog/
>>>>> Work: http://www.nordsc.com/
>>>>> -----------------------------------
>>>>> 
>>>>> 
>>>>> 
>>>>> 
>>>> 
>>>> Jan Vincent Liwanag
>>>> jvliwanag@...
>>>> 
>>>> 
>>>> 
>>> 
>>> -----------------------------------
>>> Jan Algermissen, Consultant
>>> NORD Software Consulting
>>> 
>>> Mail: algermissen@...
>>> Blog: http://www.nordsc.com/blog/
>>> Work: http://www.nordsc.com/
>>> -----------------------------------
>>> 
>>> 
>>> 
>>> 
>> 
>> Jan Vincent Liwanag
>> jvliwanag@...
>> 
>> 
>> 
> 
> -----------------------------------
> Jan Algermissen, Consultant
> NORD Software Consulting
> 
> Mail: algermissen@...
> Blog: http://www.nordsc.com/blog/
> Work: http://www.nordsc.com/
> -----------------------------------
> 
> 
> 
> 

Jan Vincent Liwanag
jvliwanag@...

On Feb 19, 2010, at 9:38 AM, Jan Vincent wrote:

> 
> First off,
> 
> Thanks for the insights. Perhaps my POV on HATEOAS still needs tweaking. Let's have some theoretical desktop client for a social network such as facebook. The desktop client say, simply needs to display the friends of some user. Now, the social network published it's API and the resources that can be accessed. Say, there are three of them
> 
> Root Resource ("/") - The only one that has a URL, and contains links to other resources, for simplicity, say this contains all the links to all its users.
> User Resource - Give some info about the user, and more importantly, it has the link to the Friends Resource of the User
> Friends Resource - Contains the list of friends, and the links to their respective User Resources
> 
> If the desktop client aims to accomplish what it's supposed to, I aim to expose two methods to be used by the application, say:
> 
> get_user_info(User)
> get_friends(User)
> 
> Internally, it traverses from the root until it ends up getting the information it needs.
> 
> If I get what you're saying though, I probably shouldn't even expose those two methods? Am I thinking about this all wrong?

Hmm, no, I don't think so. The API design is correct becasue you discover the resources at runtime through typed links.

Regarding the use case, I'd probably leverage the fact that the application you are building seems to be passive in nature, driven by a human end user. If so, you can think more in terms of a Web browser style. Web browsers typically use the processing rules of the media types to turn the steady state they are in into some GUI for the user.

So I'd probably let the server! drive the state of the GUI (or that part of the GUI) completely. E.g. turn the service document into a pane and just make every user link you find into a GUI control (item in a scrollable list) and turn the ueser's ref to it's info into a clickable element. Once clicked on, the GUI would hand that click to the user agent to have it traverse to the next steady state. this state could be handed back to the GUI fro display in another pane. And so on.

Key think here is really to make the GUI just respond to the steady state, ike a browser does. IOW, have the GUI reflect exactly what the server sent.

I am sure you shoul dbe able to leverage HTML for that quite a bit, or?

HTH,

Jan



> 
> On Feb 19, 2010, at 4:18 PM, Jan Algermissen wrote:
> 
>> 
>> On Feb 19, 2010, at 9:02 AM, Jan Vincent wrote:
>> 
>>> 
>>> On Feb 19, 2010, at 3:36 PM, Jan Algermissen wrote:
>>> 
>>>> 
>>>> On Feb 19, 2010, at 8:19 AM, Jan Vincent wrote:
>>>> 
>>>>> True enough,
>>>>> 
>>>>> Doing:
>>>>> 
>>>>>> from("/").follow( "#users_link" ).fill_form( "search_user" , {"id": "someid"}).follow( "#user_link" ).follow( "#friends_ link")
>>>>> 
>>>>> Doesn't cut it since it assumes specific responses from the server. But the point of HATEOAS I believe is that links are indeed provided for me to traverse through.
>>>> 
>>>> Yes, but you can make no assumption
>>>> a) about the media type returned
>>>> b) about what links, forms etc. you will find in there
>>> 
>>> Can't I? If the server acts right, it should recognize my Accept header.
>> 
>> There might be several types you put in the accept header. The client should handle any matching response.
>> 
>>> If it doesn't have the Content-Type that I recognize, then my client gives up. It simply doesn't know how to understand the new Content-Type. Since the client is preprogrammed, it's one limitation I should live with.
>> 
>> Yes. However, I like to emphasize that with REST it des not stop there because you do not just have 'broken communication' but in fact still an ongoing communication (a benefit of uniform status codes) and it makes sense to think about leveraging that situation. You could, for example, have the client open an RFC ticket in some helpdesk system to trigger an ASAP update of the client capabilities. I consider that different from dumping a stack trace in the logs and calling a developer with 'uhh - something is wrong'.
>> 
>> Technically, yes - at some point you just need to give up.
>> 
>>> 
>>>> 
>>>>> I may instead represent this as some form of tree, perhaps something like:
>>>>> 
>>>>> from("/").follow("#users_link" ).handle({
>>>>> 200: fill_form("search_user" , ...)...
>>>>> 404: ...
>>>>> })
>>>> 
>>>> The 200 still does not mean that the form will be there (or that the response will be in a media type that you expect)
>>>> Also, what about 201,202,303,204.... you have to handle all of those, too. ... yes, the REST client side is hard ...
>>>> 
>>> If I do a GET, i should expect a 200 if it exists, 404 otherwise. I can choose logical defaults for 3xx series possibly make it transparent to the programmer unless he chooses to do so. 5xx series, well, that would raise exception. Same with PUT, POST, etc, there are certain status codes the client should expect, some status codes wherein default action would be ok, and the rest, that simply won't make sense (i.e., a 201 on a GET request).
>> 
>> Yes. I wanted to stress the point that you should handle those codes that make sense (202 on GET also, IMO). But as long as you think along the lines you describe that's ok I guess.
>> 
>> 
>>>> 
>>>>> 
>>>>> On the other hand, I would rather do the previous one and handle exceptions instead.
>>>> 
>>>> Well, you can, of course. But you must understand that what you handle as exceptions does not mean the server behaves incorrect because any valid HTTP response is part of the contract. The exceptions would essentially only handle the client side 'broken' implementation.
>>>> 
>>>>> The client should know some information about the server's state machine right?
>>>> 
>>>> No! That is the essence of the hypermedia constraint. It must look at each steady state in isolation and 'make the best of it' in a sense.
>>>> 
>>>> Note that this influences the issue of media type design substantially because you can design types that make this very hard or types that makethis easier.
>>> 
>>> It doesn't have to learn of the entire server's state machine, but just enough of it. The clients need some prior knowledge on how to jump from one resource to another,
>> 
>> It must know the media type to understand the meaning of the current transitions. It can then coose the transition that advances its built-in goal but it cannot have any expectation about what is being returned by the server.
>> 
>> (Note that the client *can* expect for the server to not lie, e.g. <img src=""/> must point to an image, <app:collection href=""/> must point to a collection.)
>> 
>> 
>>> possibly in the form of xpath, json traversal rules, or rdf relationships.
>> 
>> What do you mean here? I did not get that.
>> 
>> 
>> 
>>> 
>>>> 
>>>>> And if it asks right, it should rightfully expect that it gets the content-type it requested for.
>>>> 
>>>> Still, if it gets a 406 it should be able to handle that and not just dump an exception into the logs.
>>> 
>>> What else is there to do? Unless some AI stuff is going on, I don't think it can do much to recover.
>> 
>> See above: leverage the still existing conversation. In addition, think more in terms of 'client is not able to reach its overall goal' from the current steady state as opposed to 'the server did not send me what it should have - that's an exception'. Even if the end result is about the same - the style inthinging is different.
>> 
>> 
>>> 
>>>> 
>>>>> How else would it be able to do its task?
>>>> 
>>>> By knowing the set of media types to expect and by handling every media type for every response.
>>> 
>>> Exactly. There are some assumptions that must be in place -- certain expectations how the server can act.
>>> 
>>> I'm curious though. Say for a social network API, how would some client know who the friends are of some user?
>> 
>> What do you mean?
>> 
>> 
>> Jan
>> 
>> 
>> 
>>> 
>>>> 
>>>> 
>>>> Jan
>>>> 
>>>>> 
>>>>> On Feb 19, 2010, at 3:05 PM, Jan Algermissen wrote:
>>>>> 
>>>>>> 
>>>>>> On Feb 19, 2010, at 8:03 AM, Jan Algermissen wrote:
>>>>>> 
>>>>>>> 
>>>>>>> [1] In my opinion, the client must know the types at design time - otherwise, the client could not be coded in the first place
>>>>>> 
>>>>>> Meant to add this link to some thoughts about this: http://www.nordsc.com/blog/?cat=4
>>>>>> 
>>>>>> Jan
>>>>>> 
>>>>>> 
>>>>>>> 
>>>>>>> 
>>>>>>>> 
>>>>>>>> In reality of course, this shouldn't really necessitate multiple calls to the server if called multiple times since previous results have been cached and processed on the client side. Only when the cache expires, should there be an attempt to request again. I'm not really sure if RESTful clients that respect HATEOAS do it this way, and should they in the first place. If they do, are there tools that exist for this?
>>>>>>>> 
>>>>>>>> On a side note, content type negotiation should be preconfigured before doing the call I stated above.
>>>>>>>> 
>>>>>>>> Thanks,
>>>>>>>> 
>>>>>>>> Jan Vincent Liwanag
>>>>>>>> jvliwanag@...
>>>>>>>> 
>>>>>>>> 
>>>>>>>> 
>>>>>>>> 
>>>>>>>> 
>>>>>>>> ------------------------------------
>>>>>>>> 
>>>>>>>> Yahoo! Groups Links
>>>>>>>> 
>>>>>>>> 
>>>>>>>> 
>>>>>>> 
>>>>>>> -----------------------------------
>>>>>>> Jan Algermissen, Consultant
>>>>>>> NORD Software Consulting
>>>>>>> 
>>>>>>> Mail: algermissen@...
>>>>>>> Blog: http://www.nordsc.com/blog/
>>>>>>> Work: http://www.nordsc.com/
>>>>>>> -----------------------------------
>>>>>>> 
>>>>>>> 
>>>>>>> 
>>>>>>> 
>>>>>>> 
>>>>>>> 
>>>>>>> ------------------------------------
>>>>>>> 
>>>>>>> Yahoo! Groups Links
>>>>>>> 
>>>>>>> 
>>>>>>> 
>>>>>> 
>>>>>> -----------------------------------
>>>>>> Jan Algermissen, Consultant
>>>>>> NORD Software Consulting
>>>>>> 
>>>>>> Mail: algermissen@...
>>>>>> Blog: http://www.nordsc.com/blog/
>>>>>> Work: http://www.nordsc.com/
>>>>>> -----------------------------------
>>>>>> 
>>>>>> 
>>>>>> 
>>>>>> 
>>>>> 
>>>>> Jan Vincent Liwanag
>>>>> jvliwanag@...
>>>>> 
>>>>> 
>>>>> 
>>>> 
>>>> -----------------------------------
>>>> Jan Algermissen, Consultant
>>>> NORD Software Consulting
>>>> 
>>>> Mail: algermissen@...
>>>> Blog: http://www.nordsc.com/blog/
>>>> Work: http://www.nordsc.com/
>>>> -----------------------------------
>>>> 
>>>> 
>>>> 
>>>> 
>>> 
>>> Jan Vincent Liwanag
>>> jvliwanag@...
>>> 
>>> 
>>> 
>> 
>> -----------------------------------
>> Jan Algermissen, Consultant
>> NORD Software Consulting
>> 
>> Mail: algermissen@...
>> Blog: http://www.nordsc.com/blog/
>> Work: http://www.nordsc.com/
>> -----------------------------------
>> 
>> 
>> 
>> 
> 
> Jan Vincent Liwanag
> jvliwanag@...
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

REST-minus

or

URI-oriented

I would not consider anything an abuse of REST unless they are making
false claims to be REST-full.

I wrote an article along these lines a while back:

http://codeartisan.blogspot.com/2009/01/websites-are-also-restful-web-se
rvices.html

 

The basic idea is something very similar to what you're describing
below, Jan; implement your API using HTML as the media type, which lets
you navigate it in a browser while you're prototyping/implementing. This
is powerful for a couple of reasons: (1) playing with the API in a web
browser is much more convenient and natural for a programmer than trying
to poke at endpoints with curl or other client programs; (2) it pushes
you in a HATEOAS direction. For example, if I'm processing a conditional
PUT, and I want to return a 412 (Precondition Failed), it leads me to
put *something* in the response body, because I want to show that
programmer something in the browser. Probably I would put the current
version of the resource with another <form> for editing it.

 

But now, if I also add program-friendly representations for the
resources (Atom, JSON, etc.), then I've now set up a programmatic client
with enough context to continue along with whatever it's trying to do,
and probably without requiring extra round-trips to the server. i.e. my
client doesn't have to have logic like "if I get a 412, do another GET,
then try to do your PUT again". Instead, it can say "ah, I got a 412 in
response to my PUT; does the representation I got back match my desired
state or not?" followed either by moving onto the next goal or doing a
new PUT, as desired.

 

Jon

 

________________________________

From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com]
On Behalf Of Jan Algermissen
Sent: Friday, February 19, 2010 4:25 AM
To: Jan Vincent
Cc: rest-discuss@yahoogroups.com
Subject: Re: [rest-discuss] HATEOAS and Cache

 

  


On Feb 19, 2010, at 9:38 AM, Jan Vincent wrote:

> 
> First off,
> 
> Thanks for the insights. Perhaps my POV on HATEOAS still needs
tweaking. Let's have some theoretical desktop client for a social
network such as facebook. The desktop client say, simply needs to
display the friends of some user. Now, the social network published it's
API and the resources that can be accessed. Say, there are three of them
> 
> Root Resource ("/") - The only one that has a URL, and contains links
to other resources, for simplicity, say this contains all the links to
all its users.
> User Resource - Give some info about the user, and more importantly,
it has the link to the Friends Resource of the User
> Friends Resource - Contains the list of friends, and the links to
their respective User Resources
> 
> If the desktop client aims to accomplish what it's supposed to, I aim
to expose two methods to be used by the application, say:
> 
> get_user_info(User)
> get_friends(User)
> 
> Internally, it traverses from the root until it ends up getting the
information it needs.
> 
> If I get what you're saying though, I probably shouldn't even expose
those two methods? Am I thinking about this all wrong?

Hmm, no, I don't think so. The API design is correct becasue you
discover the resources at runtime through typed links.

Regarding the use case, I'd probably leverage the fact that the
application you are building seems to be passive in nature, driven by a
human end user. If so, you can think more in terms of a Web browser
style. Web browsers typically use the processing rules of the media
types to turn the steady state they are in into some GUI for the user.

So I'd probably let the server! drive the state of the GUI (or that part
of the GUI) completely. E.g. turn the service document into a pane and
just make every user link you find into a GUI control (item in a
scrollable list) and turn the ueser's ref to it's info into a clickable
element. Once clicked on, the GUI would hand that click to the user
agent to have it traverse to the next steady state. this state could be
handed back to the GUI fro display in another pane. And so on.

Key think here is really to make the GUI just respond to the steady
state, ike a browser does. IOW, have the GUI reflect exactly what the
server sent.

I am sure you shoul dbe able to leverage HTML for that quite a bit, or?

HTH,

Jan

> 
> On Feb 19, 2010, at 4:18 PM, Jan Algermissen wrote:
> 
>> 
>> On Feb 19, 2010, at 9:02 AM, Jan Vincent wrote:
>> 
>>> 
>>> On Feb 19, 2010, at 3:36 PM, Jan Algermissen wrote:
>>> 
>>>> 
>>>> On Feb 19, 2010, at 8:19 AM, Jan Vincent wrote:
>>>> 
>>>>> True enough,
>>>>> 
>>>>> Doing:
>>>>> 
>>>>>> from("/").follow( "#users_link" ).fill_form( "search_user" ,
{"id": "someid"}).follow( "#user_link" ).follow( "#friends_ link")
>>>>> 
>>>>> Doesn't cut it since it assumes specific responses from the
server. But the point of HATEOAS I believe is that links are indeed
provided for me to traverse through.
>>>> 
>>>> Yes, but you can make no assumption
>>>> a) about the media type returned
>>>> b) about what links, forms etc. you will find in there
>>> 
>>> Can't I? If the server acts right, it should recognize my Accept
header.
>> 
>> There might be several types you put in the accept header. The client
should handle any matching response.
>> 
>>> If it doesn't have the Content-Type that I recognize, then my client
gives up. It simply doesn't know how to understand the new Content-Type.
Since the client is preprogrammed, it's one limitation I should live
with.
>> 
>> Yes. However, I like to emphasize that with REST it des not stop
there because you do not just have 'broken communication' but in fact
still an ongoing communication (a benefit of uniform status codes) and
it makes sense to think about leveraging that situation. You could, for
example, have the client open an RFC ticket in some helpdesk system to
trigger an ASAP update of the client capabilities. I consider that
different from dumping a stack trace in the logs and calling a developer
with 'uhh - something is wrong'.
>> 
>> Technically, yes - at some point you just need to give up.
>> 
>>> 
>>>> 
>>>>> I may instead represent this as some form of tree, perhaps
something like:
>>>>> 
>>>>> from("/").follow("#users_link" ).handle({
>>>>> 200: fill_form("search_user" , ...)...
>>>>> 404: ...
>>>>> })
>>>> 
>>>> The 200 still does not mean that the form will be there (or that
the response will be in a media type that you expect)
>>>> Also, what about 201,202,303,204.... you have to handle all of
those, too. ... yes, the REST client side is hard ...
>>>> 
>>> If I do a GET, i should expect a 200 if it exists, 404 otherwise. I
can choose logical defaults for 3xx series possibly make it transparent
to the programmer unless he chooses to do so. 5xx series, well, that
would raise exception. Same with PUT, POST, etc, there are certain
status codes the client should expect, some status codes wherein default
action would be ok, and the rest, that simply won't make sense (i.e., a
201 on a GET request).
>> 
>> Yes. I wanted to stress the point that you should handle those codes
that make sense (202 on GET also, IMO). But as long as you think along
the lines you describe that's ok I guess.
>> 
>> 
>>>> 
>>>>> 
>>>>> On the other hand, I would rather do the previous one and handle
exceptions instead.
>>>> 
>>>> Well, you can, of course. But you must understand that what you
handle as exceptions does not mean the server behaves incorrect because
any valid HTTP response is part of the contract. The exceptions would
essentially only handle the client side 'broken' implementation.
>>>> 
>>>>> The client should know some information about the server's state
machine right?
>>>> 
>>>> No! That is the essence of the hypermedia constraint. It must look
at each steady state in isolation and 'make the best of it' in a sense.
>>>> 
>>>> Note that this influences the issue of media type design
substantially because you can design types that make this very hard or
types that makethis easier.
>>> 
>>> It doesn't have to learn of the entire server's state machine, but
just enough of it. The clients need some prior knowledge on how to jump
from one resource to another,
>> 
>> It must know the media type to understand the meaning of the current
transitions. It can then coose the transition that advances its built-in
goal but it cannot have any expectation about what is being returned by
the server.
>> 
>> (Note that the client *can* expect for the server to not lie, e.g.
<img src=""/> must point to an image, <app:collection href=""/> must
point to a collection.)
>> 
>> 
>>> possibly in the form of xpath, json traversal rules, or rdf
relationships.
>> 
>> What do you mean here? I did not get that.
>> 
>> 
>> 
>>> 
>>>> 
>>>>> And if it asks right, it should rightfully expect that it gets the
content-type it requested for.
>>>> 
>>>> Still, if it gets a 406 it should be able to handle that and not
just dump an exception into the logs.
>>> 
>>> What else is there to do? Unless some AI stuff is going on, I don't
think it can do much to recover.
>> 
>> See above: leverage the still existing conversation. In addition,
think more in terms of 'client is not able to reach its overall goal'
from the current steady state as opposed to 'the server did not send me
what it should have - that's an exception'. Even if the end result is
about the same - the style inthinging is different.
>> 
>> 
>>> 
>>>> 
>>>>> How else would it be able to do its task?
>>>> 
>>>> By knowing the set of media types to expect and by handling every
media type for every response.
>>> 
>>> Exactly. There are some assumptions that must be in place -- certain
expectations how the server can act.
>>> 
>>> I'm curious though. Say for a social network API, how would some
client know who the friends are of some user?
>> 
>> What do you mean?
>> 
>> 
>> Jan
>> 
>> 
>> 
>>> 
>>>> 
>>>> 
>>>> Jan
>>>> 
>>>>> 
>>>>> On Feb 19, 2010, at 3:05 PM, Jan Algermissen wrote:
>>>>> 
>>>>>> 
>>>>>> On Feb 19, 2010, at 8:03 AM, Jan Algermissen wrote:
>>>>>> 
>>>>>>> 
>>>>>>> [1] In my opinion, the client must know the types at design time
- otherwise, the client could not be coded in the first place
>>>>>> 
>>>>>> Meant to add this link to some thoughts about this:
http://www.nordsc.com/blog/?cat=4 <http://www.nordsc.com/blog/?cat=4> 
>>>>>> 
>>>>>> Jan
>>>>>> 
>>>>>> 
>>>>>>> 
>>>>>>> 
>>>>>>>> 
>>>>>>>> In reality of course, this shouldn't really necessitate
multiple calls to the server if called multiple times since previous
results have been cached and processed on the client side. Only when the
cache expires, should there be an attempt to request again. I'm not
really sure if RESTful clients that respect HATEOAS do it this way, and
should they in the first place. If they do, are there tools that exist
for this?
>>>>>>>> 
>>>>>>>> On a side note, content type negotiation should be
preconfigured before doing the call I stated above.
>>>>>>>> 
>>>>>>>> Thanks,
>>>>>>>> 
>>>>>>>> Jan Vincent Liwanag
>>>>>>>> jvliwanag@... <mailto:jvliwanag%40gmail.com> 
>>>>>>>> 
>>>>>>>> 
>>>>>>>> 
>>>>>>>> 
>>>>>>>> 
>>>>>>>> ------------------------------------
>>>>>>>> 
>>>>>>>> Yahoo! Groups Links
>>>>>>>> 
>>>>>>>> 
>>>>>>>> 
>>>>>>> 
>>>>>>> -----------------------------------
>>>>>>> Jan Algermissen, Consultant
>>>>>>> NORD Software Consulting
>>>>>>> 
>>>>>>> Mail: algermissen@... <mailto:algermissen%40acm.org> 
>>>>>>> Blog: http://www.nordsc.com/blog/ <http://www.nordsc.com/blog/> 
>>>>>>> Work: http://www.nordsc.com/ <http://www.nordsc.com/> 
>>>>>>> -----------------------------------
>>>>>>> 
>>>>>>> 
>>>>>>> 
>>>>>>> 
>>>>>>> 
>>>>>>> 
>>>>>>> ------------------------------------
>>>>>>> 
>>>>>>> Yahoo! Groups Links
>>>>>>> 
>>>>>>> 
>>>>>>> 
>>>>>> 
>>>>>> -----------------------------------
>>>>>> Jan Algermissen, Consultant
>>>>>> NORD Software Consulting
>>>>>> 
>>>>>> Mail: algermissen@... <mailto:algermissen%40acm.org> 
>>>>>> Blog: http://www.nordsc.com/blog/ <http://www.nordsc.com/blog/> 
>>>>>> Work: http://www.nordsc.com/ <http://www.nordsc.com/> 
>>>>>> -----------------------------------
>>>>>> 
>>>>>> 
>>>>>> 
>>>>>> 
>>>>> 
>>>>> Jan Vincent Liwanag
>>>>> jvliwanag@... <mailto:jvliwanag%40gmail.com> 
>>>>> 
>>>>> 
>>>>> 
>>>> 
>>>> -----------------------------------
>>>> Jan Algermissen, Consultant
>>>> NORD Software Consulting
>>>> 
>>>> Mail: algermissen@... <mailto:algermissen%40acm.org> 
>>>> Blog: http://www.nordsc.com/blog/ <http://www.nordsc.com/blog/> 
>>>> Work: http://www.nordsc.com/ <http://www.nordsc.com/> 
>>>> -----------------------------------
>>>> 
>>>> 
>>>> 
>>>> 
>>> 
>>> Jan Vincent Liwanag
>>> jvliwanag@... <mailto:jvliwanag%40gmail.com> 
>>> 
>>> 
>>> 
>> 
>> -----------------------------------
>> Jan Algermissen, Consultant
>> NORD Software Consulting
>> 
>> Mail: algermissen@... <mailto:algermissen%40acm.org> 
>> Blog: http://www.nordsc.com/blog/ <http://www.nordsc.com/blog/> 
>> Work: http://www.nordsc.com/ <http://www.nordsc.com/> 
>> -----------------------------------
>> 
>> 
>> 
>> 
> 
> Jan Vincent Liwanag
> jvliwanag@... <mailto:jvliwanag%40gmail.com> 
> 
> 
> 

-----------------------------------
Jan Algermissen, Consultant
NORD Software Consulting

Mail: algermissen@... <mailto:algermissen%40acm.org> 
Blog: http://www.nordsc.com/blog/ <http://www.nordsc.com/blog/> 
Work: http://www.nordsc.com/ <http://www.nordsc.com/> 
-----------------------------------

On Tue, Feb 16, 2010 at 3:39 PM, Jan Algermissen <algermissen1971@...>wrote:

>
> Any ideas?
>
>
What about RES'  - that's 3/4s.

-Randy Fischer

- resent, now CCed list -

On Feb 19, 2010, at 1:26 PM, Bob Haugen wrote:

> REST-minus

I actually like that.

Gee - I should have asked on StackOverflow so people could vote for the best name :)



> 
> or
> 
> URI-oriented
> 
> I would not consider anything an abuse of REST unless they are making
> false claims to be REST-full.

Yes.
Jan



> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
Jan Algermissen, Consultant
NORD Software Consulting

Mail: algermissen@...
Blog: http://www.nordsc.com/blog/
Work: http://www.nordsc.com/
-----------------------------------

I like Restless. Easy to roll of the tongue like Restful. "Is your API RESTful or RESTless?"



--- On Fri, 2/19/10, Jan Algermissen <algermissen1971@mac.com> wrote:

From: Jan Algermissen <algermissen1971@...>
Subject: Re: [rest-discuss] Re: A Name for "3 out of 4 REST constraints" APIs?
To: "Bob Haugen" <bob.haugen@...>
Cc: "REST Discuss" <rest-discuss@yahoogroups.com>
Date: Friday, February 19, 2010, 6:40 AM







 



  


    
      
      
      - resent, now CCed list -



On Feb 19, 2010, at 1:26 PM, Bob Haugen wrote:



> REST-minus



I actually like that.



Gee - I should have asked on StackOverflow so people could vote for the best name :)



> 

> or

> 

> URI-oriented

> 

> I would not consider anything an abuse of REST unless they are making

> false claims to be REST-full.



Yes.

Jan



> 

> 

> ------------ --------- --------- ------

> 

> Yahoo! Groups Links

> 

> 

> 



------------ --------- --------- -----

Jan Algermissen, Consultant

NORD Software Consulting



Mail: algermissen@ acm.org

Blog: http://www.nordsc. com/blog/

Work: http://www.nordsc. com/

------------ --------- --------- -----





    
     

    
    


 



  






      

Quite some time ago I wrote a little sample app, based mostly on an article by Paul James [1] which was a simple digest auth implementation. Now perhaps my memory has gone soggy, but I'm sure that there was a workaround to avoid the annoying pop-up dialog being displayed (something like you had to make sure that the response length was at least 420 characters).

Well, I just ran the sample again and for the life of me I can't suppress the dialog (in order to replace it with something prettier that uses AJAX to carry out the actual auth handshake). Has there been fix work done on recent browser versions to stop this end-around? If so (or even if not, for that matter) does anyone have a way of doing it?

Thanks,
Alan

[1] http://www.peej.co.uk/articles/http-auth-with-html-forms.html

Hi Alan,

At the time Paul wrote this article I tried implementing his approach  
into an application I was working on.  Unfortunately I was unable to  
use it due to a bug in a Safari.  The relevant bug report is here: https://bugs.webkit.org/show_bug.cgi?id=8291

Cheers
Adam

On 20/02/2010, at 12:17 PM, Alan Dean wrote:

> Quite some time ago I wrote a little sample app, based mostly on an  
> article by Paul James [1] which was a simple digest auth  
> implementation. Now perhaps my memory has gone soggy, but I'm sure  
> that there was a workaround to avoid the annoying pop-up dialog  
> being displayed (something like you had to make sure that the  
> response length was at least 420 characters).
>
> Well, I just ran the sample again and for the life of me I can't  
> suppress the dialog (in order to replace it with something prettier  
> that uses AJAX to carry out the actual auth handshake). Has there  
> been fix work done on recent browser versions to stop this end- 
> around? If so (or even if not, for that matter) does anyone have a  
> way of doing it?
>
> Thanks,
> Alan
>
> [1] http://www.peej.co.uk/articles/http-auth-with-html-forms.html
>
>
> 

Speaking of HTML, how do you assert something (PUT) via HATEOAS? I was wondering why the URI templates in the forms didn't go through. I believe it still counts as hypermedia.

Here's what I mean. Say, I have a resource consisting, say, a list of rabbits. I wanna assert that some rabbit exist by hopefully PUTting on the URL it's assigned to.

/rabbits -> the link I'm provided with
/rabbits/brown_one -> the one I need to PUT to

Let's consider Case A:

The brown_one resource exists. It's link is listed on the rabbits resource. I can simply follow the link to /rabbits/brown_one, and I might expect a form there to modify the resource. That's great.

Case B:

The brown_one resource doesn't exist yet. It's not listed on the rabbits resource. The standard one perhaps is to fill up a form on /rabbits to create a new one. If it's done right, it's gonna be a POST to the current resource (/rabbits).

A better form however, should have allowed me to assert that some brown_one exists, creating it if necessary. But that would use some URI template on the form, something like:

<form method="PUT" action="/rabbits/{type}">
<input name="type".../>
...</form>

The first solution for Case B isn't so convenient, since I accomplish 'assertion' via checking some resource, then POST-ing to it, rather than PUT. The second one however is non-standard but more uniform (it's supposed to work whether or not there exists a brown_one in the first place). A third but not so great solution is to have some resource that can offer up a link to something that may not exist yet -- there's gonna be a /rabbits/brown_one link somehow but GET-ting it is gonna be a 404 while a form is being made available if I want to fill it up.

What do you guys think?


On Feb 19, 2010, at 9:04 PM, Moore, Jonathan wrote:

> 
> 
> I wrote an article along these lines a while back:
> http://codeartisan.blogspot.com/2009/01/websites-are-also-restful-web-services.html
>  
> The basic idea is something very similar to what you�re describing below, Jan; implement your API using HTML as the media type, which lets you navigate it in a browser while you�re prototyping/implementing. This is powerful for a couple of reasons: (1) playing with the API in a web browser is much more convenient and natural for a programmer than trying to poke at endpoints with curl or other client programs; (2) it pushes you in a HATEOAS direction. For example, if I�m processing a conditional PUT, and I want to return a 412 (Precondition Failed), it leads me to put *something* in the response body, because I want to show that programmer something in the browser. Probably I would put the current version of the resource with another <form> for editing it.
>  
> But now, if I also add program-friendly representations for the resources (Atom, JSON, etc.), then I�ve now set up a programmatic client with enough context to continue along with whatever it�s trying to do, and probably without requiring extra round-trips to the server. i.e. my client doesn�t have to have logic like �if I get a 412, do another GET, then try to do your PUT again�. Instead, it can say �ah, I got a 412 in response to my PUT; does the representation I got back match my desired state or not?� followed either by moving onto the next goal or doing a new PUT, as desired.
>  
> Jon
>  
> From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com] On Behalf Of Jan Algermissen
> Sent: Friday, February 19, 2010 4:25 AM
> To: Jan Vincent
> Cc: rest-discuss@yahoogroups.com
> Subject: Re: [rest-discuss] HATEOAS and Cache
>  
>  
> 
> On Feb 19, 2010, at 9:38 AM, Jan Vincent wrote:
> 
> > 
> > First off,
> > 
> > Thanks for the insights. Perhaps my POV on HATEOAS still needs tweaking. Let's have some theoretical desktop client for a social network such as facebook. The desktop client say, simply needs to display the friends of some user. Now, the social network published it's API and the resources that can be accessed. Say, there are three of them
> > 
> > Root Resource ("/") - The only one that has a URL, and contains links to other resources, for simplicity, say this contains all the links to all its users.
> > User Resource - Give some info about the user, and more importantly, it has the link to the Friends Resource of the User
> > Friends Resource - Contains the list of friends, and the links to their respective User Resources
> > 
> > If the desktop client aims to accomplish what it's supposed to, I aim to expose two methods to be used by the application, say:
> > 
> > get_user_info(User)
> > get_friends(User)
> > 
> > Internally, it traverses from the root until it ends up getting the information it needs.
> > 
> > If I get what you're saying though, I probably shouldn't even expose those two methods? Am I thinking about this all wrong?
> 
> Hmm, no, I don't think so. The API design is correct becasue you discover the resources at runtime through typed links.
> 
> Regarding the use case, I'd probably leverage the fact that the application you are building seems to be passive in nature, driven by a human end user. If so, you can think more in terms of a Web browser style. Web browsers typically use the processing rules of the media types to turn the steady state they are in into some GUI for the user.
> 
> So I'd probably let the server! drive the state of the GUI (or that part of the GUI) completely. E.g. turn the service document into a pane and just make every user link you find into a GUI control (item in a scrollable list) and turn the ueser's ref to it's info into a clickable element. Once clicked on, the GUI would hand that click to the user agent to have it traverse to the next steady state. this state could be handed back to the GUI fro display in another pane. And so on.
> 
> Key think here is really to make the GUI just respond to the steady state, ike a browser does. IOW, have the GUI reflect exactly what the server sent.
> 
> I am sure you shoul dbe able to leverage HTML for that quite a bit, or?
> 
> HTH,
> 
> Jan
> 
> > 
> > On Feb 19, 2010, at 4:18 PM, Jan Algermissen wrote:
> > 
> >> 
> >> On Feb 19, 2010, at 9:02 AM, Jan Vincent wrote:
> >> 
> >>> 
> >>> On Feb 19, 2010, at 3:36 PM, Jan Algermissen wrote:
> >>> 
> >>>> 
> >>>> On Feb 19, 2010, at 8:19 AM, Jan Vincent wrote:
> >>>> 
> >>>>> True enough,
> >>>>> 
> >>>>> Doing:
> >>>>> 
> >>>>>> from("/").follow( "#users_link" ).fill_form( "search_user" , {"id": "someid"}).follow( "#user_link" ).follow( "#friends_ link")
> >>>>> 
> >>>>> Doesn't cut it since it assumes specific responses from the server. But the point of HATEOAS I believe is that links are indeed provided for me to traverse through.
> >>>> 
> >>>> Yes, but you can make no assumption
> >>>> a) about the media type returned
> >>>> b) about what links, forms etc. you will find in there
> >>> 
> >>> Can't I? If the server acts right, it should recognize my Accept header.
> >> 
> >> There might be several types you put in the accept header. The client should handle any matching response.
> >> 
> >>> If it doesn't have the Content-Type that I recognize, then my client gives up. It simply doesn't know how to understand the new Content-Type. Since the client is preprogrammed, it's one limitation I should live with.
> >> 
> >> Yes. However, I like to emphasize that with REST it des not stop there because you do not just have 'broken communication' but in fact still an ongoing communication (a benefit of uniform status codes) and it makes sense to think about leveraging that situation. You could, for example, have the client open an RFC ticket in some helpdesk system to trigger an ASAP update of the client capabilities. I consider that different from dumping a stack trace in the logs and calling a developer with 'uhh - something is wrong'.
> >> 
> >> Technically, yes - at some point you just need to give up.
> >> 
> >>> 
> >>>> 
> >>>>> I may instead represent this as some form of tree, perhaps something like:
> >>>>> 
> >>>>> from("/").follow("#users_link" ).handle({
> >>>>> 200: fill_form("search_user" , ...)...
> >>>>> 404: ...
> >>>>> })
> >>>> 
> >>>> The 200 still does not mean that the form will be there (or that the response will be in a media type that you expect)
> >>>> Also, what about 201,202,303,204.... you have to handle all of those, too. ... yes, the REST client side is hard ...
> >>>> 
> >>> If I do a GET, i should expect a 200 if it exists, 404 otherwise. I can choose logical defaults for 3xx series possibly make it transparent to the programmer unless he chooses to do so. 5xx series, well, that would raise exception. Same with PUT, POST, etc, there are certain status codes the client should expect, some status codes wherein default action would be ok, and the rest, that simply won't make sense (i.e., a 201 on a GET request).
> >> 
> >> Yes. I wanted to stress the point that you should handle those codes that make sense (202 on GET also, IMO). But as long as you think along the lines you describe that's ok I guess.
> >> 
> >> 
> >>>> 
> >>>>> 
> >>>>> On the other hand, I would rather do the previous one and handle exceptions instead.
> >>>> 
> >>>> Well, you can, of course. But you must understand that what you handle as exceptions does not mean the server behaves incorrect because any valid HTTP response is part of the contract. The exceptions would essentially only handle the client side 'broken' implementation.
> >>>> 
> >>>>> The client should know some information about the server's state machine right?
> >>>> 
> >>>> No! That is the essence of the hypermedia constraint. It must look at each steady state in isolation and 'make the best of it' in a sense.
> >>>> 
> >>>> Note that this influences the issue of media type design substantially because you can design types that make this very hard or types that makethis easier.
> >>> 
> >>> It doesn't have to learn of the entire server's state machine, but just enough of it. The clients need some prior knowledge on how to jump from one resource to another,
> >> 
> >> It must know the media type to understand the meaning of the current transitions. It can then coose the transition that advances its built-in goal but it cannot have any expectation about what is being returned by the server.
> >> 
> >> (Note that the client *can* expect for the server to not lie, e.g. <img src=""/> must point to an image, <app:collection href=""/> must point to a collection.)
> >> 
> >> 
> >>> possibly in the form of xpath, json traversal rules, or rdf relationships.
> >> 
> >> What do you mean here? I did not get that.
> >> 
> >> 
> >> 
> >>> 
> >>>> 
> >>>>> And if it asks right, it should rightfully expect that it gets the content-type it requested for.
> >>>> 
> >>>> Still, if it gets a 406 it should be able to handle that and not just dump an exception into the logs.
> >>> 
> >>> What else is there to do? Unless some AI stuff is going on, I don't think it can do much to recover.
> >> 
> >> See above: leverage the still existing conversation. In addition, think more in terms of 'client is not able to reach its overall goal' from the current steady state as opposed to 'the server did not send me what it should have - that's an exception'. Even if the end result is about the same - the style inthinging is different.
> >> 
> >> 
> >>> 
> >>>> 
> >>>>> How else would it be able to do its task?
> >>>> 
> >>>> By knowing the set of media types to expect and by handling every media type for every response.
> >>> 
> >>> Exactly. There are some assumptions that must be in place -- certain expectations how the server can act.
> >>> 
> >>> I'm curious though. Say for a social network API, how would some client know who the friends are of some user?
> >> 
> >> What do you mean?
> >> 
> >> 
> >> Jan
> >> 
> >> 
> >> 
> >>> 
> >>>> 
> >>>> 
> >>>> Jan
> >>>> 
> >>>>> 
> >>>>> On Feb 19, 2010, at 3:05 PM, Jan Algermissen wrote:
> >>>>> 
> >>>>>> 
> >>>>>> On Feb 19, 2010, at 8:03 AM, Jan Algermissen wrote:
> >>>>>> 
> >>>>>>> 
> >>>>>>> [1] In my opinion, the client must know the types at design time - otherwise, the client could not be coded in the first place
> >>>>>> 
> >>>>>> Meant to add this link to some thoughts about this: http://www.nordsc.com/blog/?cat=4
> >>>>>> 
> >>>>>> Jan
> >>>>>> 
> >>>>>> 
> >>>>>>> 
> >>>>>>> 
> >>>>>>>> 
> >>>>>>>> In reality of course, this shouldn't really necessitate multiple calls to the server if called multiple times since previous results have been cached and processed on the client side. Only when the cache expires, should there be an attempt to request again. I'm not really sure if RESTful clients that respect HATEOAS do it this way, and should they in the first place. If they do, are there tools that exist for this?
> >>>>>>>> 
> >>>>>>>> On a side note, content type negotiation should be preconfigured before doing the call I stated above.
> >>>>>>>> 
> >>>>>>>> Thanks,
> >>>>>>>> 
> >>>>>>>> Jan Vincent Liwanag
> >>>>>>>> jvliwanag@...
> >>>>>>>> 
> >>>>>>>> 
> >>>>>>>> 
> >>>>>>>> 
> >>>>>>>> 
> >>>>>>>> ------------------------------------
> >>>>>>>> 
> >>>>>>>> Yahoo! Groups Links
> >>>>>>>> 
> >>>>>>>> 
> >>>>>>>> 
> >>>>>>> 
> >>>>>>> -----------------------------------
> >>>>>>> Jan Algermissen, Consultant
> >>>>>>> NORD Software Consulting
> >>>>>>> 
> >>>>>>> Mail: algermissen@...
> >>>>>>> Blog: http://www.nordsc.com/blog/
> >>>>>>> Work: http://www.nordsc.com/
> >>>>>>> -----------------------------------
> >>>>>>> 
> >>>>>>> 
> >>>>>>> 
> >>>>>>> 
> >>>>>>> 
> >>>>>>> 
> >>>>>>> ------------------------------------
> >>>>>>> 
> >>>>>>> Yahoo! Groups Links
> >>>>>>> 
> >>>>>>> 
> >>>>>>> 
> >>>>>> 
> >>>>>> -----------------------------------
> >>>>>> Jan Algermissen, Consultant
> >>>>>> NORD Software Consulting
> >>>>>> 
> >>>>>> Mail: algermissen@...
> >>>>>> Blog: http://www.nordsc.com/blog/
> >>>>>> Work: http://www.nordsc.com/
> >>>>>> -----------------------------------
> >>>>>> 
> >>>>>> 
> >>>>>> 
> >>>>>> 
> >>>>> 
> >>>>> Jan Vincent Liwanag
> >>>>> jvliwanag@gmail.com
> >>>>> 
> >>>>> 
> >>>>> 
> >>>> 
> >>>> -----------------------------------
> >>>> Jan Algermissen, Consultant
> >>>> NORD Software Consulting
> >>>> 
> >>>> Mail: algermissen@...
> >>>> Blog: http://www.nordsc.com/blog/
> >>>> Work: http://www.nordsc.com/
> >>>> -----------------------------------
> >>>> 
> >>>> 
> >>>> 
> >>>> 
> >>> 
> >>> Jan Vincent Liwanag
> >>> jvliwanag@...
> >>> 
> >>> 
> >>> 
> >> 
> >> -----------------------------------
> >> Jan Algermissen, Consultant
> >> NORD Software Consulting
> >> 
> >> Mail: algermissen@...
> >> Blog: http://www.nordsc.com/blog/
> >> Work: http://www.nordsc.com/
> >> -----------------------------------
> >> 
> >> 
> >> 
> >> 
> > 
> > Jan Vincent Liwanag
> > jvliwanag@gmail.com
> > 
> > 
> > 
> 
> -----------------------------------
> Jan Algermissen, Consultant
> NORD Software Consulting
> 
> Mail: algermissen@acm.org
> Blog: http://www.nordsc.com/blog/
> Work: http://www.nordsc.com/
> -----------------------------------
> 
> 
> 
> 

Jan Vincent Liwanag
jvliwanag@...

Markus,

[let me in general suggest again to use the correct term 'hypermedia constraint' instead of the silly acronym...]

On Feb 20, 2010, at 3:29 PM, Markus Karg wrote:

> This discussion started on users@... and was moved to rest-discuss as it is a general REST topic and less a particular Jersey topic. Please send comments only torest-discuss@yahoogroups.com but not to users@.... Thanks. :-)

Good!

>  
> As Roy Fielding pointed out several times, an API must not call itself RESTful as long as it is not applying HATEOAS. I want to support this constraint by adding HATEOASfulness to my future applications. One thing I just do not understand so far about HATEOAS-via-HTTP is (and what other people asked me when citing Fielding in this issue): How a client shall actually know which http method to use to follow a link received with the previous request to a RESTful server? Roy answered in his blog that the method could be read out of the last result. But actually how?

This information is part of the hypermedia semantics specified (media type specification or link relation specification etc). Such a specification can either explicitly state the method to use (see RFC 5023 for example) or specify a hypermedia element that tells the client at runtime what method to use (e.g. HTML forms).


>  
> I understand that typically one would use e. g. http "Link" headers or e. g. XLink in XML content to model HATEOAS transformation URIs. But the problem is that in reality neither the "Link" header nor XLink provide the possibility to declare the http method used on that URI.

Right. The specification of the link relation would have to do that.

> So my client can learn from the previous http request what the URI is to place an order, but it does not see which http method must be used to place it (whether it is a PUT or a POST for example, since both could be valid in theory).

Right. Suppose you'd use an AtomPub collection to tell the client about the order processor:

<app:collection href="/orders/">
  <app:accept>application/procurement+xml;type=order</app:accept>
</app:collection>

Then you would know from RFC5023 that the method to use is POST.

There is really no technical magic going on - it all must be specified and implemented by the client (or the client plugin loaded for processing the primary media type of the current steady state).

Jan

> I understand that in a perfect world, I could apply the common sense for the CRUD-via-http pattern on that resource (PUT, GET, POST, DELETE), but it might be not so obvious in all cases which of that methods is actually right to achieve a particular business task, since the business use case is beyond simple CRUD, as there might be more than one way to RESTfully model a complex business case.
>  
> Fielding wrote in his blog that the client will learn about the http methods by inspecting the last response, just as it learned about the possible URIs. But how to actually achieve this in reality, aside from the purely theoretical idea? Is the actual solution really to break down all business cases to CRUD atoms (and such to unambiguity of http methods)?
>  
> I already searched the archive for this but could not find a working real-world solution (maybe I used the wrong keyword when searching?).
>  
> Thanks
> Markus
>  

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Considering four constraints I don't really like the RESTless term, 
because RESTfull obviously means fulfilling all four constraints, but 
RESTless could also mean to fulfill  not one of the constraints, but we 
like to express "all but one", I think.

So reading the nice suggestions I would prefer REST-wheas application 
(whithout hipermedia engine of application state) to stress that there 
is something missed, or to say what it is with a more positive tone: 
HTTP-based application.

Regards,
Daniel


Am 19.02.2010 19:11, schrieb Kevin Duffey:
>
> I like Restless. Easy to roll of the tongue like Restful. "Is your API 
> RESTful or RESTless?"
>
>
>
> --- On *Fri, 2/19/10, Jan Algermissen /<algermissen1971@...>/* wrote:
>
>
>     From: Jan Algermissen <algermissen1971@...>
>     Subject: Re: [rest-discuss] Re: A Name for "3 out of 4 REST
>     constraints" APIs?
>     To: "Bob Haugen" <bob.haugen@...>
>     Cc: "REST Discuss" <rest-discuss@yahoogroups.com>
>     Date: Friday, February 19, 2010, 6:40 AM
>
>     - resent, now CCed list -
>
>     On Feb 19, 2010, at 1:26 PM, Bob Haugen wrote:
>
>     > REST-minus
>
>     I actually like that.
>
>     Gee - I should have asked on StackOverflow so people could vote
>     for the best name :)
>
>     >
>     > or
>     >
>     > URI-oriented
>     >
>     > I would not consider anything an abuse of REST unless they are
>     making
>     > false claims to be REST-full.
>
>     Yes.
>     Jan
>
>     >
>     >
>     > ------------ --------- --------- ------
>     >
>     > Yahoo! Groups Links
>     >
>     >
>     >
>
>     ------------ --------- --------- -----
>     Jan Algermissen, Consultant
>     NORD Software Consulting
>
>     Mail: algermissen@ acm.org </mc/compose?to=algermissen%40acm.org>
>     Blog: http://www.nordsc. com/blog/ <http://www.nordsc.com/blog/>
>     Work: http://www.nordsc. com/ <http://www.nordsc.com/>
>     ------------ --------- --------- -----
>
>
> 

-- 
Daniel "Oscar" Schulte

This discussion started on users@... and was moved to
rest-discuss as it is a general REST topic and less a particular Jersey
topic. Please send comments only to rest-discuss@yahoogroups.com but not to
users@.... Thanks. :-)

 

As Roy Fielding pointed out several times, an API must not call itself
RESTful as long as it is not applying HATEOAS. I want to support this
constraint by adding HATEOASfulness to my future applications. One thing I
just do not understand so far about HATEOAS-via-HTTP is (and what other
people asked me when citing Fielding in this issue): How a client shall
actually know which http method to use to follow a link received with the
previous request to a RESTful server? Roy answered in his blog that the
method could be read out of the last result. But actually how?

 

I understand that typically one would use e. g. http "Link" headers or e. g.
XLink in XML content to model HATEOAS transformation URIs. But the problem
is that in reality neither the "Link" header nor XLink provide the
possibility to declare the http method used on that URI. So my client can
learn from the previous http request what the URI is to place an order, but
it does not see which http method must be used to place it (whether it is a
PUT or a POST for example, since both could be valid in theory). I
understand that in a perfect world, I could apply the common sense for the
CRUD-via-http pattern on that resource (PUT, GET, POST, DELETE), but it
might be not so obvious in all cases which of that methods is actually right
to achieve a particular business task, since the business use case is beyond
simple CRUD, as there might be more than one way to RESTfully model a
complex business case.

 

Fielding wrote in his blog that the client will learn about the http methods
by inspecting the last response, just as it learned about the possible URIs.
But how to actually achieve this in reality, aside from the purely
theoretical idea? Is the actual solution really to break down all business
cases to CRUD atoms (and such to unambiguity of http methods)?

 

I already searched the archive for this but could not find a working
real-world solution (maybe I used the wrong keyword when searching?).

 

Thanks

Markus

> > As Roy Fielding pointed out several times, an API must not call
> itself RESTful as long as it is not applying HATEOAS. I want to support
> this constraint by adding HATEOASfulness to my future applications. One
> thing I just do not understand so far about HATEOAS-via-HTTP is (and
> what other people asked me when citing Fielding in this issue): How a
> client shall actually know which http method to use to follow a link
> received with the previous request to a RESTful server? Roy answered in
> his blog that the method could be read out of the last result. But
> actually how?
> 
> This information is part of the hypermedia semantics specified (media
> type specification or link relation specification etc). Such a
> specification can either explicitly state the method to use (see RFC
> 5023 for example) or specify a hypermedia element that tells the client
> at runtime what method to use (e.g. HTML forms).

I understand that with AtomPub RFC5023 specifies that. Call me dumb, but
what to do if I am not using AtomPub but self-made service (like a web shop
application)? How to do it then? For example, if I am writing a web shop, an
that one allows to place an order using a POST. How to tell a client that it
shall use that POST? I mean, *where* to put that information in a technical
sense?
 

On Feb 20, 2010, at 7:16 PM, Markus KARG wrote:

>>> As Roy Fielding pointed out several times, an API must not call
>> itself RESTful as long as it is not applying HATEOAS. I want to support
>> this constraint by adding HATEOASfulness to my future applications. One
>> thing I just do not understand so far about HATEOAS-via-HTTP is (and
>> what other people asked me when citing Fielding in this issue): How a
>> client shall actually know which http method to use to follow a link
>> received with the previous request to a RESTful server? Roy answered in
>> his blog that the method could be read out of the last result. But
>> actually how?
>> 
>> This information is part of the hypermedia semantics specified (media
>> type specification or link relation specification etc). Such a
>> specification can either explicitly state the method to use (see RFC
>> 5023 for example) or specify a hypermedia element that tells the client
>> at runtime what method to use (e.g. HTML forms).
> 
> I understand that with AtomPub RFC5023 specifies that. Call me dumb, but
> what to do if I am not using AtomPub but self-made service (like a web shop
> application)? How to do it then? For example, if I am writing a web shop, an
> that one allows to place an order using a POST. How to tell a client that it
> shall use that POST? I mean, *where* to put that information in a technical
> sense?
> 

In the specification of the media type (or link relation etc.) you are using.

If you do not have something like that, that specifies the semantics of your application[1] nobody can code a client that can interact with the application. Unless the client is ultimately driven by a human.

AtomPub takes you quite far usually, though in my work, I use a somewhat extended version that provides for the description of 'single' resources and for search forms[2]. I actually cannot see anything I would like to describe about the start state of a service that cannot be expressed with that extended form of AtomPub.

The client developer needs to read the media type or link relation spec and simple put that knowledge into the client code (be it directly or as a plugin).

Jan



[1] Usually, we would want such specs for kinds of applications, of course, not just a single one.
[2] http://www.nordsc.com/blog/?p=80
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

And this is related to REST because?

_________________________________________________

Melhores cumprimentos / Beir beannacht / Best regards

Ant�nio Manuel dos Santos Mota

http://card.ly/amsmota
_________________________________________________



On 20 February 2010 04:24, Adam Ratcliffe <adam@...> wrote:

>
>
> Hi Alan,
>
> At the time Paul wrote this article I tried implementing his approach into
> an application I was working on.  Unfortunately I was unable to use it due
> to a bug in a Safari.  The relevant bug report is here:
> https://bugs.webkit.org/show_bug.cgi?id=8291
>
> Cheers
> Adam
>
> On 20/02/2010, at 12:17 PM, Alan Dean wrote:
>
> Quite some time ago I wrote a little sample app, based mostly on an article
> by Paul James [1] which was a simple digest auth implementation. Now perhaps
> my memory has gone soggy, but I'm sure that there was a workaround to avoid
> the annoying pop-up dialog being displayed (something like you had to make
> sure that the response length was at least 420 characters).
>
> Well, I just ran the sample again and for the life of me I can't suppress
> the dialog (in order to replace it with something prettier that uses AJAX to
> carry out the actual auth handshake). Has there been fix work done on recent
> browser versions to stop this end-around? If so (or even if not, for that
> matter) does anyone have a way of doing it?
>
> Thanks,
> Alan
>
> [1] http://www.peej.co.uk/articles/http-auth-with-html-forms.html
>
>
>  
>

António,

Because I need to carry out auth on a REST service with resources which are
surfaced to humans as (x)html as well as to machine-to-machine interactions.

At the moment, I've inherited a cookie-based system but wish to refactor
that away (I don't think that I need to convince this audience why) but, as
you can imagine, the butt-ugly dialog gives my product owners an excellent
reason to override the preferred technical choice.

Auth is frequent bugbear to us RESTafarians and I figured that someone else
on the list has probably seen this change and (possibly) has an answer that
allows use of a standardized auth mechanism (HTTP Digest) rather than
yet-another-custom-token scheme.

Regards,
Alan Dean


2010/2/20 António Mota <amsmota@...>

> And this is related to REST because?
>
> _________________________________________________
>
> Melhores cumprimentos / Beir beannacht / Best regards
>
> António Manuel dos Santos Mota
>
> http://card.ly/amsmota
> _________________________________________________
>
>
>
> On 20 February 2010 04:24, Adam Ratcliffe <adam@...> wrote:
>
>>
>>
>> Hi Alan,
>>
>> At the time Paul wrote this article I tried implementing his approach into
>> an application I was working on.  Unfortunately I was unable to use it due
>> to a bug in a Safari.  The relevant bug report is here:
>> https://bugs.webkit.org/show_bug.cgi?id=8291
>>
>> Cheers
>> Adam
>>
>> On 20/02/2010, at 12:17 PM, Alan Dean wrote:
>>
>> Quite some time ago I wrote a little sample app, based mostly on an
>> article by Paul James [1] which was a simple digest auth implementation. Now
>> perhaps my memory has gone soggy, but I'm sure that there was a workaround
>> to avoid the annoying pop-up dialog being displayed (something like you had
>> to make sure that the response length was at least 420 characters).
>>
>> Well, I just ran the sample again and for the life of me I can't suppress
>> the dialog (in order to replace it with something prettier that uses AJAX to
>> carry out the actual auth handshake). Has there been fix work done on recent
>> browser versions to stop this end-around? If so (or even if not, for that
>> matter) does anyone have a way of doing it?
>>
>> Thanks,
>> Alan
>>
>> [1] http://www.peej.co.uk/articles/http-auth-with-html-forms.html
>>
>>
>>  
>>
>
>

Hello guys,

Jan Vincent, answering your question about the cache, Restfulie and
Exylus are the only two clients APIs that I am aware of supporting
cache (according to the restwiki). You can see how it works here:

http://guilhermesilveira.wordpress.com/2010/01/26/scaling-through-rest-why-rest-clients-require-cache-support/

> Also, what about 201,202,303,204.... you have to handle all of those, too. ... yes, the REST client side is hard ...

Jan, since it seems impossible to write code answering every response
code at every request, Restfulie, for example, allows you to register
default handlers, and already provides a set of defaults (i.e. 201
will follow and retrieve the resource).

Regards

Guilherme Silveira
Caelum | Ensino e Inova��o
http://www.caelum.com.br/

Hey all,


 



  








How are you authenticating users with REST calls other than Basic Auth? I am looking into OAuth.. setting it up is a bit of a chore. Looking to use this one example I found with opensso.�
I am basically looking to do something like how Google Maps and other REST apis require a developer to get a token to be able to make calls to the API. I am fine if it's not OAuth, but I would like to better understand and/or get some help from one of you security experts out there on how to get this working.
So in a nutshell, I'll have a "dev" test box, and a production setup. I want a way for a developer to get some sort of token for either/both, but am finding myself getting a little lost with all the key/secret stuff. For now I basically want to be able to authenticate all API calls coming in with some way to make sure it's something I gave the user to allow them access. I am not sure if this is referred to as 2-legged or 3-legged in OAuth terms. I think it's two-legged.. and is that good enough?
Any pointers to examples that explain how I can deploy my own token generator and how a client would make a call to get a token, then make a call to any API with the token (or token/key?), and so on would be much appreciated.


      

On Feb 18, 2010, at 10:21 AM, Robert Brewer wrote:
> Eric J. Bowman wrote:
> > I contend that the format of a representation is part of a
> > system's hierarchical data.  The proof is right there in curl,
> > which sees no hierarchy when it's saving 'resource' and
> > 'resource.1' to disk, while obviously recognizing .pdf
> > and .html as part of a hierarchy of representations, whether
> > by direct dereferencing or by presence in a Content-Location
> > response header.
> 
> That's an odd way to look at it. The "format of a representation
> is part of a system's hierarchical data" if and only if the path
> portion of the URI contains information to that effect. If not,
> it doesn't. The fact that some domains specifically do this does
> not require them all to do so. Curl is suboptimal in this respect
> since it does not differentiate responses based on the query
> string component.

More to the point, one implementation doesn't "prove" anything.

> > But it's still treating URIs opaquely -- links are derived from
> > the link relations in the source documents, which are read from
> > @href's. There is no analysis of those @href contents by keyword
> > or filename extension to determine "resource type".  Clients
> > aren't required to know any specifics of a URI's pattern.  That
> > would be coupling, which is diametrically opposed to the notion
> > of URI opacity in REST.
> 
> Absolutely correct. That behavior should be extended to query string
> components of the URI as well.
> 
> > Don't get carried away by saying that my treating URIs as
> > hierarchical or testing whether they have fragments or not,
> > amounts to a failure to treat URIs as opaque.  Can you point
> > to some constraint in REST that I'm breaking?  Can you find any
> > support from Roy to back up this notion that URI opacity means
> > that query and filename extension are the same?
> 
> Sure. I used to take your position but corrected myself [1] back
> in 2005, complete with Fielding quotes and RFC 3986 references ;)
> 
> > Are there any
> > generic URI parsers you can point me to, which treat query
> > strings opaquely?  Or do they all consider '?' to be a reserved
> > character?
> 
> The '?' character does have a special meaning: it separates the
> hierarchical portion of the URI from the opaque part. But the
> opaque part is still part of the identifier.
> 
> > So the onus is not on me to prove that Roy isn't being clear
> > as daylight when he says that "query is not a substitute for
> > identification of resources", but on you who think it could
> > possibly mean any different to support *your* arguments.  :-)
> 
> When I read that statement from Roy [2], I don't see any indication
> that it's about "query" as a URI component; instead, it is regarding
> "query" as a means of fetching a list of resources. Roy's point
> seems to be that returning 38 items in a list within a single
> response is no substitute for having distinct URI's for each of
> those 38 individual resources.
> 
> 
> Robert Brewer
> fumanchu@...
> 
> [1] http://groups.google.com/group/cherrypy-devel/msg/0fcc62df334bc9ed
> [2] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-720


Right, I wasn't talking about URI syntax at all.  Any server developer
would know that the URI syntax of the request-target (URI path and query)
has absolutely no correlation to any specific "kind" of resource mapping
or implementation.  Things like mod_rewrite make that impossible.

...Roy

> > I understand that with AtomPub RFC5023 specifies that. Call me dumb,
> but
> > what to do if I am not using AtomPub but self-made service (like a
> web shop
> > application)? How to do it then? For example, if I am writing a web
> shop, an
> > that one allows to place an order using a POST. How to tell a client
> that it
> > shall use that POST? I mean, *where* to put that information in a
> technical
> > sense?
> >
> 
> In the specification of the media type (or link relation etc.) you are
> using.
> 
> If you do not have something like that, that specifies the semantics of
> your application[1] nobody can code a client that can interact with the
> application. Unless the client is ultimately driven by a human.

Ok, so let me provide an example: The media type used is based on XML, and I
am using XSL to define it's structure (special, proporietary MIME e. g.
"application/inspectionplan+xml". Maybe my XSD knowledge is not good enough,
but how do I define the http method now to be used for a particular
operation? I mean, actually, not theoretically, in machine-readable form,
not in human-readable specs?

On Feb 21, 2010, at 10:09 AM, Markus KARG wrote:

>>> I understand that with AtomPub RFC5023 specifies that. Call me dumb,
>> but
>>> what to do if I am not using AtomPub but self-made service (like a
>> web shop
>>> application)? How to do it then? For example, if I am writing a web
>> shop, an
>>> that one allows to place an order using a POST. How to tell a client
>> that it
>>> shall use that POST? I mean, *where* to put that information in a
>> technical
>>> sense?
>>> 
>> 
>> In the specification of the media type (or link relation etc.) you are
>> using.
>> 
>> If you do not have something like that, that specifies the semantics of
>> your application[1] nobody can code a client that can interact with the
>> application. Unless the client is ultimately driven by a human.
> 
> Ok, so let me provide an example: The media type used is based on XML, and I
> am using XSL to define it's structure

What do you mean by that? Ah, you meant XSD, yes?

> (special, proporietary MIME e. g.
> "application/inspectionplan+xml". Maybe my XSD knowledge is not good enough,
> but how do I define the http method now to be used for a particular
> operation? I mean, actually, not theoretically, in machine-readable form,
> not in human-readable specs?

You do not need a machine readable form.

You'd write sometiing like:

"The link relation "order-processor" is used to refer to resources that accept order submissions and you pace orders by sending the order in a POST request to to that resource"

The server would send data such as

200 Ok
Content-type: application/inspectionplan+xml

<foo>
  <bar>
  </bar>
  <link rel="order-processor" href="/orders"/>
</foo>


And in your client you would code:


if(media type == application/inspectionplan+xml) {
  linkElem = extract from body the link element that has rel=order-processor
  if(linkElem) {
     orderProcessorUri = linkElem.getAttr("href");
     // Now, this is the hard coded knowledge that POST is the method to use.
     // It comes from the spec directly.
     request = new Request("POST",orderProcessorUri,orderDocument)
     response = client.perform(request);
  }
}


This is not different from HTML specifyiing that the method for <a href=""/> is GET.

If you want a variation of the method at runtim, use a form mechanism such as HTML does, just with a specific form. You can look at the OpenSearch parameters extension as an exaple (see method attribute):

<http://www.opensearch.org/Specifications/OpenSearch/Extensions/Parameter/1.0>


Jan












> 
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

---------- Forwarded message ----------
Date: 2010/2/21
To: users@...v.java.net


That's my PUJ example :)

I have this academic competition, with "competition phases"...

So, I have professors submitting student's homeworks for a
competition, and each competition has the following phases:

1) call for papers
2) evaluation
3) history

So,

1) During the call for papers, a professor can submit a homework, or
patch the homework, delete, etc (homework CRUD). When the competition
changes to the evaluation phase, no more changes are accepted in the
homeworks, so the method PUT and POST should be "disabled" in the
homework resources.

2) During the evaluation, the "evaluators" can apply grades to the
homeworks.. They can also review their grades. methods PUT, GET,
DELETE and POST are available to the homework grades resource.

3) When the competition finishes, it goes to the history phase, and no
more changes are acceptable in the homeworks (evaluation, patches,
etc..). The resources supports only GET methods in this phase.

Notice that I have two distinct workflows here:

1) the resource workflow, where a change in the resource produces its
feasible next states as side effects.
2) the application phases, where an external action (usually the
competition owner presses a button) changes the state of all resources
regarding a competition.

Considering the competition also as a resource, I have a change in the
state of a competition with side effects in other resources. So it is
not only a matter of changing the resource representation, but also to
manage the impact of that changing in other resources.

I have an slide representing this problem in this presentation:
http://www.jfokus.se/jfokus/preso/jf-10_DomainDrivenRESTWeb-Services.pdf

Please let me know if this problem is suitable for your discussion.

I have also some code implemented about that, like:

------------- load competitions:

XML/JSON: http://fgaucho.dyndns.org:8080/arena-http/competition
JSONP: http://fgaucho.dyndns.org:8080/arena-http/competition/jsonp

------------- load homeworks:

XML/JSON: http://fgaucho.dyndns.org:8080/arena-http/homework?competition=PUJCE-09
JSONP: http://fgaucho.dyndns.org:8080/arena-http/homework/jsonp?competition=PUJCE-09

* if you don't include the 'competition' parameter, it will load all homeworks.

and I have also some write operations implemented..

It is consumed by clients like:

http://fgaucho.dyndns.org:8080/arena-dwr/
http://fgaucho.dyndns.org:8080/arena-jsf20

the code is fully available from here:

http://kenai.com/projects/puj/pages/Arena-dev

but it is still a work in progress... so be nice to tell me the missed points :)

regards,

� Felipe Ga�cho




On Sun, Feb 21, 2010 at 10:14 AM, Markus Karg <markus.karg@gmx.net> wrote:
> Tatu,
>
>
>
> no doubt about that. If you business demands storing a resource, REST will
> not prevent you from doing so. But as you said, then this is because of it's
> resource state, not of it's conversational state. The conversational state
> still must not get stored on the server. So for sake of clarity, let's not
> further use the carts example, as it would mislead readers. We should fina
> an example where undoubtful the conversation state will never get part of
> the resource state just be redefinitio of the business scenario. ;-)
>
>
>
> Regards
>
> Markus
>
>
>
> From: Tatu Saloranta [mailto:tsaloranta@...]
> Sent: Samstag, 20. Februar 2010 20:07
> To: users@...
> Subject: Re: [Jersey] RESTful Ordering (was: JAX-RS == REST? Or not? (was
> Re: [Jersey] What HATEOAS actually means))
>
>
>
>
>
> On Sat, Feb 20, 2010 at 12:09 AM, Markus Karg <markus.karg@...> wrote:
>
> Anyways, their storing of carts content of their servers was a business
> decision, not a technical one. ;-)
>
> Agreed. But I think it is an interesting case to consider -- I am sure that
> persistency (and thus statefulness) of resources is a must for many systems.
> And that it is necessary to separate resource state with session/transaction
> state. I don't think REST would preclude former, but at this point I would
> not be entirely surprised to be convinced otherwise. :-)
>
> Actually come to think of that, I can see why someone might think of
> shopping cart as conversation state... and others as more of a resource. I
> guess that is modeling choice really.
> And also a practical thing: if it is part of conversation, you can have
> multiple concurrent sessions (open a new browser window, get a different
> cart); or just a single shared one per account.
>
> FWIW, for retailers like Amazon this is obviously a must feature; not just
> shopping cart but wish lists and such. Although it is good to get immediate
> sales, probability of a later purchase is probably high (I don't know the
> ratio, nor could divulge if I did -- this is just inferred from public
> information :) ).
>
> -+ Tatu +-
>



--
------------------------------------------
� Felipe Ga�cho
� 10+ Java Programmer
� CEJUG Senior Advisor



-- 
------------------------------------------
   Felipe Ga�cho
   10+ Java Programmer
   CEJUG Senior Advisor

"Roy T. Fielding" wrote:

> On Feb 18, 2010, at 10:21 AM, Robert Brewer wrote:
> > Eric J. Bowman wrote:
> > > I contend that the format of a representation is part of a
> > > system's hierarchical data.  The proof is right there in curl,
> > > which sees no hierarchy when it's saving 'resource' and
> > > 'resource.1' to disk, while obviously recognizing .pdf
> > > and .html as part of a hierarchy of representations, whether
> > > by direct dereferencing or by presence in a Content-Location
> > > response header.
> > 
> > That's an odd way to look at it. The "format of a representation
> > is part of a system's hierarchical data" if and only if the path
> > portion of the URI contains information to that effect. If not,
> > it doesn't. The fact that some domains specifically do this does
> > not require them all to do so. Curl is suboptimal in this respect
> > since it does not differentiate responses based on the query
> > string component.
> 
> More to the point, one implementation doesn't "prove" anything.
> 

Let's not miss the forest for the trees, here.  When I use curl as an
example, it's because what I'm pointing out is accepted behavior that's
uniform amongst many clients (in this case, I've never heard anybody say
libcurl's URI parser is bugged or broken).  Try saving this URI's
content to disk using a variety of clients:

http://en.wiski.org/date?iso=2010-02-21

WebKit and Opera save based on the <title> content, so they aren't
useful examples of generic-client URI-parsing behavior (like curl).  IE
wants to save 'date' just like curl does, while Firefox wants to save
'date.xhtml' due to some sort of internal Content-Type mapping.

No client saving based on request URI (as opposed to <title> content)
asks to save 'date?iso=2010-02-21' or in any way preserves the query.
All such clients will agree what to do in the presence of a filename
extension.  So curl's behavior here is not aberrant, but represents the
norm.  Given this norm, my advice about not using query as a substitute
for filename extensions, stands.

One implementation might "disprove" this point, but I am not aware of a
single generic-URI-parser which will "differentiate responses based on
the query string component".  Arguing that curl is a bad example here,
is missing the forest for the trees, unless a counter-example is
provided which proves the common understanding is different from curl's?

-Eric

> >>> I understand that with AtomPub RFC5023 specifies that. Call me
> dumb,
> >> but
> >>> what to do if I am not using AtomPub but self-made service (like a
> >> web shop
> >>> application)? How to do it then? For example, if I am writing a web
> >> shop, an
> >>> that one allows to place an order using a POST. How to tell a
> client
> >> that it
> >>> shall use that POST? I mean, *where* to put that information in a
> >> technical
> >>> sense?
> >>>
> >>
> >> In the specification of the media type (or link relation etc.) you
> are
> >> using.
> >>
> >> If you do not have something like that, that specifies the semantics
> of
> >> your application[1] nobody can code a client that can interact with
> the
> >> application. Unless the client is ultimately driven by a human.
> >
> > Ok, so let me provide an example: The media type used is based on
> XML, and I
> > am using XSL to define it's structure
> 
> What do you mean by that? Ah, you meant XSD, yes?

Typo, sorry. Yes, obviously I meant XSD (I am using XSL a lot so my finger
type "L" automatically).
 
> > (special, proporietary MIME e. g.
> > "application/inspectionplan+xml". Maybe my XSD knowledge is not good
> enough,
> > but how do I define the http method now to be used for a particular
> > operation? I mean, actually, not theoretically, in machine-readable
> form,
> > not in human-readable specs?
> 
> You do not need a machine readable form.

If the specification is only human readable, I do not see much of a benefit
in HATEOAS at all: If the client will only be able to communicate with my
particlar implementation of a web shop (for example), in contrast to working
with *all* kinds of shops on the basis of some generic machine-readble
standard business vocabulary, then HATEOAS will not work. Why? Because
HATEOAS implies that one (even a machine) can browse to *any* URI provided
in the response of the previous call. So that is not guaranteed now, as it
will be impossible to redirect the client to a foreign site, if I (the
server vendor providing the URI) cannot guarantee that every client knows
about the particular use of http methods by that referenced site. So to make
the complete system of "machine web" work, I would have to provide
information on virtually every external service to virtually each client.
How should I know of either? This is impossible.

What would solve the problem would be a machine readable form that defines
in a unique syntax what methods will have which meaning. Such descriptions
are existing, like WADL. So what is missing is two things: (a) WADL must be
a standard, (b) It must be standardized where and how to get the WADL. If
both is provided, it won't be any problem anymore that *any* client knows
how to interprete the workflow's instruction "order this car" if it
understands the MIME type of "application/car" to get the HATEOAS links out
of it's entity, so it the URI of the "order"-titled link, and gets (from the
WADL) the mapping of "order" to "POST" for example. No human would be
involved in this process, and no human readable specification is needed. The
only thing human must tell the client is that it is part of a supply chain
management solution and shall issue "order" on a provided URI (here: the
car).

I you just rely on defining human readable specifications, you just move the
human to an early stage, but you don't get rid of him. But actually, the
difference between WWW and REST (shortly spoken) is that the first is about
humans, while the latter -in the sense we discuss it here- is about
machines. So to make it work completely (not just in part) and globally, we
need to get rid of human and find ways to make machines understand machines
without the need to manually define each single interconnection type, but
step forward to global standards. AtomPub is not a solution, as it only is
defined for publishing, while we need something on a higher level,
describing *any* kind of business interaction.

Regards
Markus

On Feb 21, 2010, at 2:23 PM, Markus KARG wrote:

> 
> If the specification is only human readable, I do not see much of a benefit
> in HATEOAS at all: If the client will only be able to communicate with my
> particlar implementation of a web shop (for example),

Right - that is why the goal should obviously be to share a 'shopping' media type across many shopping services. Such as AtomPub provides media types for implementing publishing services.


> in contrast to working
> with *all* kinds of shops on the basis of some generic machine-readble
> standard business vocabulary, then HATEOAS will not work.

> Why? Because
> HATEOAS implies that one (even a machine) can browse to *any* URI provided
> in the response of the previous call. So that is not guaranteed now, as it
> will be impossible to redirect the client to a foreign site, if I (the
> server vendor providing the URI) cannot guarantee that every client knows
> about the particular use of http methods by that referenced site. So to make
> the complete system of "machine web" work, I would have to provide
> information on virtually every external service to virtually each client.
> How should I know of either? This is impossible.
> 
> What would solve the problem

There is actually no problem - you just need an "evolving set of standard types" (to paraphrase Roy). 


> [..]
> 
> I you just rely on defining human readable specifications, you just move the
> human to an early stage, but you don't get rid of him.

It is impossible to get rid of the human otherwise we would be talking AI.

> But actually, the
> difference between WWW and REST (shortly spoken) is that the first is about
> humans, while the latter -in the sense we discuss it here- is about
> machines. So to make it work completely (not just in part) and globally, we
> need to get rid of human and find ways to make machines understand machines
> without the need to manually define each single interconnection type, but
> step forward to global standards. AtomPub is not a solution, as it only is
> defined for publishing, while we need something on a higher level,
> describing *any* kind of business interaction.

At some point you need to bind your implementation to domain semantics, no matter how many general layers you use. For example, the only difference between

<person>
  <father href=""/>
</person>

and

<person>
  <link rel="father" href=""/>
</person>

is the layer at which the 'father' semantic is defined (XML semantics vs. generic link relation semantics. You cannot make software figure out what 'father' means - you MUST hardcode that at some point.

Jan







> 
> Regards
> Markus
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

> > If the specification is only human readable, I do not see much of a
> benefit
> > in HATEOAS at all: If the client will only be able to communicate
> with my
> > particlar implementation of a web shop (for example),
> 
> Right - that is why the goal should obviously be to share a 'shopping'
> media type across many shopping services. Such as AtomPub provides
> media types for implementing publishing services.

In a pragmatic sense I agree, but in the sense of why the WWW is so great I
disagree: The long term solution shold be a machine readable declaration, so
nobody would need to agree upon which types of businesses there will be. I
mean, actually I don't provide a ship but a very specialized application. I
don't see that my few competitors would like to find a common API. But I do
see that they would agree upon something like WADL.

> > in contrast to working
> > with *all* kinds of shops on the basis of some generic machine-
> readble
> > standard business vocabulary, then HATEOAS will not work.
> 
> > Why? Because
> > HATEOAS implies that one (even a machine) can browse to *any* URI
> provided
> > in the response of the previous call. So that is not guaranteed now,
> as it
> > will be impossible to redirect the client to a foreign site, if I
> (the
> > server vendor providing the URI) cannot guarantee that every client
> knows
> > about the particular use of http methods by that referenced site. So
> to make
> > the complete system of "machine web" work, I would have to provide
> > information on virtually every external service to virtually each
> client.
> > How should I know of either? This is impossible.
> >
> > What would solve the problem
> 
> There is actually no problem - you just need an "evolving set of
> standard types" (to paraphrase Roy).

Well, actually there IS a problem, as for many businesses it is impossible
to defined a common methodology (even a common vocabulary). Also, this leads
to a plethora of business objects. I think what Roy actually meant was not
the idea that everybody should do his own type and declare it as a standard,
but more that the world negotiates upon *standard* types like Dublin Core.
Yes, that would definitively be a solution, but I do not see that it
actually is happening.

> > I you just rely on defining human readable specifications, you just
> move the
> > human to an early stage, but you don't get rid of him.
> 
> It is impossible to get rid of the human otherwise we would be talking
> AI.

No you misunderstood. I am not talking about replacing human in the workflow
sense, but only that I want to replace it at the point where he must read a
specification, as this thread is solely about http methods! So if there
would be a machine readable specification how to find out about http
methods, that does not imply any artifical intelligence, but solely solving
one particlar technical problem -- that one this thread is about.

> > But actually, the
> > difference between WWW and REST (shortly spoken) is that the first is
> about
> > humans, while the latter -in the sense we discuss it here- is about
> > machines. So to make it work completely (not just in part) and
> globally, we
> > need to get rid of human and find ways to make machines understand
> machines
> > without the need to manually define each single interconnection type,
> but
> > step forward to global standards. AtomPub is not a solution, as it
> only is
> > defined for publishing, while we need something on a higher level,
> > describing *any* kind of business interaction.
> 
> At some point you need to bind your implementation to domain semantics,
> no matter how many general layers you use. For example, the only
> difference between

I do not see that the selection of one http method is part of the domain.
"buy", "sell", "publish", "payoff" certainly are domain verbs, but the
binding of "sell" to "POST" is not, at least in my understanding, as exactly
that can be solved simply by some kind of machine-readable contract.

> <person>
>   <father href=""/>
> </person>
> 
> and
> 
> <person>
>   <link rel="father" href=""/>
> </person>
> 
> is the layer at which the 'father' semantic is defined (XML semantics
> vs. generic link relation semantics. You cannot make software figure
> out what 'father' means - you MUST hardcode that at some point.

You don't get the point of this discussion. I did nither ask nor say that a
machine shall find out what "father" means, but that I like the machine to
find out which http method to use to follow the link. Please don't imply
more general ideas into my question than I actually asked. ;-) In fact, you
need to hardcode what "father" means, but that is part of the business
domain model, while the binding of "father --> GET" is part of the technical
realization. And I am talking solely of the latter. I don't want to write a
software that can do anything. I just want to write one that ONCE I MADE IT
UNDERSTOOD WHAT A FATHER IS is able to learn about the ways to find the
father on a fully automated way. And with WADL for example that would be
possible.

On Feb 21, 2010, at 3:08 AM, Eric J. Bowman wrote:

> "Roy T. Fielding" wrote:
> 
>> On Feb 18, 2010, at 10:21 AM, Robert Brewer wrote:
>>> Eric J. Bowman wrote:
>>>> I contend that the format of a representation is part of a
>>>> system's hierarchical data.  The proof is right there in curl,
>>>> which sees no hierarchy when it's saving 'resource' and
>>>> 'resource.1' to disk, while obviously recognizing .pdf
>>>> and .html as part of a hierarchy of representations, whether
>>>> by direct dereferencing or by presence in a Content-Location
>>>> response header.
>>> 
>>> That's an odd way to look at it. The "format of a representation
>>> is part of a system's hierarchical data" if and only if the path
>>> portion of the URI contains information to that effect. If not,
>>> it doesn't. The fact that some domains specifically do this does
>>> not require them all to do so. Curl is suboptimal in this respect
>>> since it does not differentiate responses based on the query
>>> string component.
>> 
>> More to the point, one implementation doesn't "prove" anything.
> 
> Let's not miss the forest for the trees, here.  When I use curl as an
> example, it's because what I'm pointing out is accepted behavior that's
> uniform amongst many clients (in this case, I've never heard anybody say
> libcurl's URI parser is bugged or broken).

Does it work for your use case?  No.  Then it is bugged or broken.

It is accepted behavior that many clients ignore the media type when
handling text/plain content.  Is that bugged or broken?  Yes.

Browsers also typically respect content-disposition, if provided,
since their save operation occurs after reading the message,
whereas command-line tools do not.

There are many known problems in existing tools that the authors
refuse to fix because the fix would be incompatible with existing
output.  If you don't like curl's behavior, use wget (which does
save the query info as the filename).

Regardless, it is a fact that the distinction between path and
query in the URI syntax has nothing to do with how a service
is implemented or whether a given representation of a resource
can be saved as a file.  Likewise, the only relevant distinction
between file extensions and query-based media-type indicators
is that the latter are too long and far more likely to cause
undesirable cache impacts (many general-purpose caches refuse
to store responses that look like queries because, historically,
they tend to have lower hit rates than simple paths).  That's
why I always prefer extensions.

Neither choice has anything to do with REST.

....Roy

Hi all,



I am looking to start messing around with HATEOAS a bit more with my
java/jersey stuff. I am not quite sure I understand the flow of things
tho. If I publish a URI to my service I
have something like http://myservice.com/webcart as the URI. What is
the first call done.. a GET or an OPTION in order to get the possible
URIs to call next? I am trying to figure out how I start up my service
SDK that I'll publish on my site to help developers get started using
my public service.



Regardless.. I assume the response would be some sort of list of links
that can be called? I was originally turned on to this notion of using
something like as a response body:



<links>

� <link rel="self" href="http://myservice.com"/>

� <link rel="edit" href="http://myservice.com"/>

</links>



I am not quite sure tho how to specify this in the response. I know
some are talking about using the Links header..but from what I gather
it's not going to be standard until HTML5, which who knows when that
will come out.



As well, I am not quite sure how you specify the methods that can be
used.. GET, POST, PUT and DELETE. Does my SDK doc say "if rel is EDIT
then you can PUT to that URI. If it is SELF then you can only GET to
that URI"? or is there another attribute that lists the allowed methods on the URI of each link? I guess I am looking for a little help in understanding how
best to describe this HATEOAS API to other developers that will consume
it.. how to get them started, and how to explain each URI they can use
at any given point and what methods they can use on the URI, what
params, what body, etc.



In the case of a DELETE, if it succeeds.. it returns a 204 No Content.
How then do you respond with any sort of links that it can do at that
point? If it can't return any body, I can't return any <links>
with it. I think we "can" fudge it.. but then I would guess it wouldn't
be RESTful to provide any sort of body with a No Content response.
Maybe Delete doesn't have to return 204 to indicate a success?



So what are you all that have provided a HATEOAS API been doing?



Thank you.

 



  






      

On Feb 21, 2010, at 11:32 PM, Kevin Duffey wrote:

> 
> 
> Hi all,
> 
> I am looking to start messing around with HATEOAS a bit more with my java/jersey stuff.

Funny, I am just reading this[1] post about the hypermedia constraint, maybe that helps.


> I am not quite sure I understand the flow of things tho. If I publish a URI to my service I have something like http://myservice.com/webcart as the URI. What is the first call done..

It is always a GET on the URI of the entry URI the client has. This will bring the client into the corresponding entry state. Note that there might be more entry states, there is no need to limit that to a single one. In fact, any bookmarkable state can be considered an entry state. For example, when you are being sent a link to a book on Amazon, you GET it with your browser and you are right in an entry state of the Amazon shopping application.


> a GET or an OPTION in order to get the possible URIs to call next?

The next possible states will always be in your current state in the form of hypermedia constrols (links, forms). When the client understands (==implements) the media type it will understand the meaning of these transitions. (If it doesn't it'll have to give up or try something else).


> I am trying to figure out how I start up my service SDK that I'll publish on my site to help developers get started using my public service.

Do not hide the HTTP interface inside an SDK. This will only obfuscate the essence of the hypermedia constraint. Specifiy your media type or media type extensions (reuse standard types as much as possible of course) and that is all the client developer needs to know.


> 
> Regardless.. I assume the response would be some sort of list of links that can be called?

Do not approach this too 'technically'. The links can be anywhere in your hypermedia. They could be plain text, XML elements, generic link elements or forms (or take some exotic form [2])
Have a look at OpenSearch[1] or AtomPub (RFC5023) for 'learning'.


> I was originally turned on to this notion of using something like as a response body:
> 
> <links>
>   <link rel="self" href="http://myservice.com"/>
>   <link rel="edit" href="http://myservice.com"/>
> </links>

Can be like this, but absolutely need not be.

> 
> I am not quite sure tho how to specify this in the response. I know some are talking about using the Links header..but from what I gather it's not going to be standard until HTML5, which who knows when that will come out.

(Link header is orthogonal to HTML5. Consider it standard right now. It has already been in an earlier ersion of HTTP, too)

> 
> As well, I am not quite sure how you specify the methods that can be used..

Write it up in the specification of your hypermedia controls (See my last posting on that, too).

> GET, POST, PUT and DELETE. Does my SDK doc say "if rel is EDIT then you can PUT to that URI.

Yes, but not your SDK doc but the media type (or link relation-) specification. Just like HTML does for <a>, <img> or <form>

> If it is SELF then you can only GET to that URI"? or is there another attribute that lists the allowed methods on the URI of each link? I guess I am looking for a little help in understanding how best to describe this HATEOAS API to other developers that will consume it.. how to get them started, and how to explain each URI they can use at any given point and what methods they can use on the URI, what params, what body, etc.

Just do the equivalent of AtomPub or OpenSearch for what you need your service to enable.


> 
> In the case of a DELETE, if it succeeds.. it returns a 204 No Content.

Maybe. Or a 303 See other, or a 202 Accepted ...

> How then do you respond with any sort of links that it can do at that point? If it can't return any body, I can't return any <links> with it.

Right. The point you are (correctly) making here is what to consider the steady state after a 204. My personal opinion is that the steady state remains the one you were in before. If that had changed, the server should have sent you a 303 See Other to reload that state.

(There is a lot to be leveraged from the HTTP codes themselves!)


> I think we "can" fudge it.. but then I would guess it wouldn't be RESTful to provide any sort of body with a No Content response. Maybe Delete doesn't have to return 204 to indicate a success?
> 
> So what are you all that have provided a HATEOAS API been doing?

Enjoy your travel towards the next hypermedia constraint[4] 'aha-moment'. It will surely come.

Jan


> 
> Thank you.
> 


[1] http://tech.groups.yahoo.com/group/rest-discuss/message/8377
[2] http://www.nordsc.com/blog/?p=293#cbcID-tweak
[3] http://www.opensearch.org
[4] You see me hammering on the correct term as opposed to the acronym, don't you :-)




> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

On Feb 22, 2010, at 12:06 AM, Jan Algermissen wrote:

> a GET on the URI of the entry URI

Doh - too late :-)

"a GET on the entry URI" ....

This information may give you some ideas on how to approach creating and
documenting your REST-ful service API.
http://code.google.com/p/implementing-rest/wiki/RESTAPIRules

mca
http://amundsen.com/blog/



On Sun, Feb 21, 2010 at 17:32, Kevin Duffey <andjarnic@...> wrote:

>
>
> Hi all,
>
> I am looking to start messing around with HATEOAS a bit more with my
> java/jersey stuff. I am not quite sure I understand the flow of things tho.
> If I publish a URI to my service I have something like
> http://myservice.com/webcart as the URI. What is the first call done.. a
> GET or an OPTION in order to get the possible URIs to call next? I am trying
> to figure out how I start up my service SDK that I'll publish on my site to
> help developers get started using my public service.
>
> Regardless.. I assume the response would be some sort of list of links that
> can be called? I was originally turned on to this notion of using something
> like as a response body:
>
> <links>
>   <link rel="self" href="http://myservice.com"/>
>   <link rel="edit" href="http://myservice.com"/>
> </links>
>
> I am not quite sure tho how to specify this in the response. I know some
> are talking about using the Links header..but from what I gather it's not
> going to be standard until HTML5, which who knows when that will come out.
>
> As well, I am not quite sure how you specify the methods that can be used..
> GET, POST, PUT and DELETE. Does my SDK doc say "if rel is EDIT then you can
> PUT to that URI. If it is SELF then you can only GET to that URI"? or is
> there another attribute that lists the allowed methods on the URI of each
> link? I guess I am looking for a little help in understanding how best to
> describe this HATEOAS API to other developers that will consume it.. how to
> get them started, and how to explain each URI they can use at any given
> point and what methods they can use on the URI, what params, what body, etc.
>
> In the case of a DELETE, if it succeeds.. it returns a 204 No Content. How
> then do you respond with any sort of links that it can do at that point? If
> it can't return any body, I can't return any <links> with it. I think we
> "can" fudge it.. but then I would guess it wouldn't be RESTful to provide
> any sort of body with a No Content response. Maybe Delete doesn't have to
> return 204 to indicate a success?
>
> So what are you all that have provided a HATEOAS API been doing?
>
> Thank you.
>
>
>
>
> 

Ok..looking at the OpenSearch stuff.. interesting. So they basically describe the document that can be returned, and each element within it.

Maybe you can shed some light on the media type thing. That stills confuses me a bit. I read somewhere that for my java/jersey rest services, I should support a media type like vnd+com.mypackage.myclass+xml and so on. Should each and every method I support for each URL have a specific media type? I've seen a few posts now saying it's all about the media types. Ok.. what does that mean exactly? From the media type can you determine what to call on it? In other words, should I have a specific media type specified for a given resource that handles a POST for a single item, and a different media type for a POST that handles multiple items (for example, posting a new item to a web cart, or posting the entire web cart at one shot to "check out")?

Along the same lines, the OpenSearch seems to be a single resource. So I suppose I would have a document for each resource that indicates the elements that can come back in a response.. and in some cases some elements may not be part of the response. In the case of one resource call that responds with a URI to another resource, that would be documented in some manner as well... not sure how exactly.



--- On Sun, 2/21/10, Jan Algermissen <algermissen1971@...> wrote:

From: Jan Algermissen <algermissen1971@...>
Subject: Re: [rest-discuss] How do I help developers get started using my HATEOAS API?
To: "Kevin Duffey" <andjarnic@...>
Cc: rest-discuss@yahoogroups.com
Date: Sunday, February 21, 2010, 3:06 PM


On Feb 21, 2010, at 11:32 PM, Kevin Duffey wrote:

> 
> 
> Hi all,
> 
> I am looking to start messing around with HATEOAS a bit more with my java/jersey stuff.

Funny, I am just reading this[1] post about the hypermedia constraint, maybe that helps.


> I am not quite sure I understand the flow of things tho. If I publish a URI to my service I have something like http://myservice.com/webcart as the URI. What is the first call done..

It is always a GET on the URI of the entry URI the client has. This will bring the client into the corresponding entry state. Note that there might be more entry states, there is no need to limit that to a single one. In fact, any bookmarkable state can be considered an entry state. For example, when you are being sent a link to a book on Amazon, you GET it with your browser and you are right in an entry state of the Amazon shopping application.


> a GET or an OPTION in order to get the possible URIs to call next?

The next possible states will always be in your current state in the form of hypermedia constrols (links, forms). When the client understands (==implements) the media type it will understand the meaning of these transitions. (If it doesn't it'll have to give up or try something else).


> I am trying to figure out how I start up my service SDK that I'll publish on my site to help developers get started using my public service.

Do not hide the HTTP interface inside an SDK. This will only obfuscate the essence of the hypermedia constraint. Specifiy your media type or media type extensions (reuse standard types as much as possible of course) and that is all the client developer needs to know.


> 
> Regardless.. I assume the response would be some sort of list of links that can be called?

Do not approach this too 'technically'. The links can be anywhere in your hypermedia. They could be plain text, XML elements, generic link elements or forms (or take some exotic form [2])
Have a look at OpenSearch[1] or AtomPub (RFC5023) for 'learning'.


> I was originally turned on to this notion of using something like as a response body:
> 
> <links>
>���<link rel="self" href="http://myservice.com"/>
>���<link rel="edit" href="http://myservice.com"/>
> </links>

Can be like this, but absolutely need not be.

> 
> I am not quite sure tho how to specify this in the response. I know some are talking about using the Links header..but from what I gather it's not going to be standard until HTML5, which who knows when that will come out.

(Link header is orthogonal to HTML5. Consider it standard right now. It has already been in an earlier ersion of HTTP, too)

> 
> As well, I am not quite sure how you specify the methods that can be used..

Write it up in the specification of your hypermedia controls (See my last posting on that, too).

> GET, POST, PUT and DELETE. Does my SDK doc say "if rel is EDIT then you can PUT to that URI.

Yes, but not your SDK doc but the media type (or link relation-) specification. Just like HTML does for <a>, <img> or <form>

> If it is SELF then you can only GET to that URI"? or is there another attribute that lists the allowed methods on the URI of each link? I guess I am looking for a little help in understanding how best to describe this HATEOAS API to other developers that will consume it.. how to get them started, and how to explain each URI they can use at any given point and what methods they can use on the URI, what params, what body, etc.

Just do the equivalent of AtomPub or OpenSearch for what you need your service to enable.


> 
> In the case of a DELETE, if it succeeds.. it returns a 204 No Content.

Maybe. Or a 303 See other, or a 202 Accepted ...

> How then do you respond with any sort of links that it can do at that point? If it can't return any body, I can't return any <links> with it.

Right. The point you are (correctly) making here is what to consider the steady state after a 204. My personal opinion is that the steady state remains the one you were in before. If that had changed, the server should have sent you a 303 See Other to reload that state.

(There is a lot to be leveraged from the HTTP codes themselves!)


> I think we "can" fudge it.. but then I would guess it wouldn't be RESTful to provide any sort of body with a No Content response. Maybe Delete doesn't have to return 204 to indicate a success?
> 
> So what are you all that have provided a HATEOAS API been doing?

Enjoy your travel towards the next hypermedia constraint[4] 'aha-moment'. It will surely come.

Jan


> 
> Thank you.
> 


[1] http://tech.groups.yahoo.com/group/rest-discuss/message/8377
[2] http://www.nordsc.com/blog/?p=293#cbcID-tweak
[3] http://www.opensearch.org
[4] You see me hammering on the correct term as opposed to the acronym, don't you :-)




> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------







      

Hi everyone,

I have a functionality that I would like to describe in a REST fashion. Because it is effectively an idempotent transform of input to output, I would usually describe it as Resources with addresses like http://example.dom/transformed_result?input1=1&input2=y or some other equivalent URL scheme, and use GET.
Except in this case, my input is a large text (csv) that can be passed as POST input rather than GET. What are my options? The first thing that comes to mind is uploading the csv creating a new resource in the process and GETting another resource that holds the result of the transform. Only that I never need the created csv resource again and that it will be multiple HTTP requests for what warrants in my opinion a single one.

Any help is appreciated.

Regards,

Muhammad Alkarouri

>>>>> "malkarouri" == malkarouri  <malkarouri@...> writes:

    malkarouri> Only that I never need the created csv resource again
    malkarouri> and that it will be multiple HTTP requests for what
    malkarouri> warrants in my opinion a single one.

So that is clearly useless. Just use a POST.

-- 
Cheers,

Berend de Boer

On Feb 22, 2010, at 1:45 AM, Kevin Duffey wrote:

> 
> 
> Ok..looking at the OpenSearch stuff.. interesting. So they basically describe the document that can be returned, and each element within it.
> 
> Maybe you can shed some light on the media type thing. That stills confuses me a bit. I read somewhere that for my java/jersey rest services, I should support a media type like vnd+com.mypackage.myclass+xml and so on. Should each and every method I support for each URL have a specific media type?

Huh? No, why do you think so? Just ask yourself:

When I receive a response of type application/opensearchdescription+xml what possibilities are there for next state transitions? Hint: look at the spec of that media type.


> I've seen a few posts now saying it's all about the media types. Ok.. what does that mean exactly? From the media type can you determine what to call on it?

Exacty. How does your browser implementor know, what to do and what the method is if a user clicks on an <a> link? How does she know what to do and what the method is in the case of an HTML <form> submission? Check the section "Protocol Operations" in RFC5023 (AtomPub).

> In other words, should I have a specific media type specified for a given resource that handles a POST for a single item, and a different media type for a POST that handles multiple items (for example, posting a new item to a web cart, or posting the entire web cart at one shot to "check out")?

The media type does not describe the resource of the next request. It just describes how to interprete the representation that the client holds *now*. The meaning of the links is what is being described.


> 
> Along the same lines, the OpenSearch seems to be a single resource.

??? That sentence does not make sense.

> So I suppose I would have a document for each resource that indicates the elements that can come back in a response..

> and in some cases some elements may not be part of the response. In the case of one resource call that responds with a URI to another resource, that would be documented in some manner as well... not sure how exactly.

Again, look at AtomPub <service> documents and Opensearch description (not the search result) documents. What do they tell you?

Jan


> 
> 
> 
> --- On Sun, 2/21/10, Jan Algermissen <algermissen1971@...> wrote:
> 
> From: Jan Algermissen <algermissen1971@...>
> Subject: Re: [rest-discuss] How do I help developers get started using my HATEOAS API?
> To: "Kevin Duffey" <andjarnic@...>
> Cc: rest-discuss@yahoogroups.com
> Date: Sunday, February 21, 2010, 3:06 PM
> 
> 
> On Feb 21, 2010, at 11:32 PM, Kevin Duffey wrote:
> 
> > 
> > 
> > Hi all,
> > 
> > I am looking to start messing around with HATEOAS a bit more with my java/jersey stuff.
> 
> Funny, I am just reading this[1] post about the hypermedia constraint, maybe that helps.
> 
> 
> > I am not quite sure I understand the flow of things tho. If I publish a URI to my service I have something likehttp://myservice.com/webcart as the URI. What is the first call done..
> 
> It is always a GET on the URI of the entry URI the client has. This will bring the client into the corresponding entry state. Note that there might be more entry states, there is no need to limit that to a single one. In fact, any bookmarkable state can be considered an entry state. For example, when you are being sent a link to a book on Amazon, you GET it with your browser and you are right in an entry state of the Amazon shopping application.
> 
> 
> > a GET or an OPTION in order to get the possible URIs to call next?
> 
> The next possible states will always be in your current state in the form of hypermedia constrols (links, forms). When the client understands (==implements) the media type it will understand the meaning of these transitions. (If it doesn't it'll have to give up or try something else).
> 
> 
> > I am trying to figure out how I start up my service SDK that I'll publish on my site to help developers get started using my public service.
> 
> Do not hide the HTTP interface inside an SDK. This will only obfuscate the essence of the hypermedia constraint. Specifiy your media type or media type extensions (reuse standard types as much as possible of course) and that is all the client developer needs to know.
> 
> 
> > 
> > Regardless.. I assume the response would be some sort of list of links that can be called?
> 
> Do not approach this too 'technically'. The links can be anywhere in your hypermedia. They could be plain text, XML elements, generic link elements or forms (or take some exotic form [2])
> Have a look at OpenSearch[1] or AtomPub (RFC5023) for 'learning'.
> 
> 
> > I was originally turned on to this notion of using something like as a response body:
> > 
> > <links>
> >   <link rel="self" href="http://myservice.com"/>
> >   <link rel="edit" href="http://myservice.com"/>
> > </links>
> 
> Can be like this, but absolutely need not be.
> 
> > 
> > I am not quite sure tho how to specify this in the response. I know some are talking about using the Links header..but from what I gather it's not going to be standard until HTML5, which who knows when that will come out.
> 
> (Link header is orthogonal to HTML5. Consider it standard right now. It has already been in an earlier ersion of HTTP, too)
> 
> > 
> > As well, I am not quite sure how you specify the methods that can be used..
> 
> Write it up in the specification of your hypermedia controls (See my last posting on that, too).
> 
> > GET, POST, PUT and DELETE. Does my SDK doc say "if rel is EDIT then you can PUT to that URI.
> 
> Yes, but not your SDK doc but the media type (or link relation-) specification. Just like HTML does for <a>, <img> or <form>
> 
> > If it is SELF then you can only GET to that URI"? or is there another attribute that lists the allowed methods on the URI of each link? I guess I am looking for a little help in understanding how best to describe this HATEOAS API to other developers that will consume it.. how to get them started, and how to explain each URI they can use at any given point and what methods they can use on the URI, what params, what body, etc.
> 
> Just do the equivalent of AtomPub or OpenSearch for what you need your service to enable.
> 
> 
> > 
> > In the case of a DELETE, if it succeeds.. it returns a 204 No Content.
> 
> Maybe. Or a 303 See other, or a 202 Accepted ...
> 
> > How then do you respond with any sort of links that it can do at that point? If it can't return any body, I can't return any <links> with it.
> 
> Right. The point you are (correctly) making here is what to consider the steady state after a 204. My personal opinion is that the steady state remains the one you were in before. If that had changed, the server should have sent you a 303 See Other to reload that state.
> 
> (There is a lot to be leveraged from the HTTP codes themselves!)
> 
> 
> > I think we "can" fudge it.. but then I would guess it wouldn't be RESTful to provide any sort of body with a No Content response. Maybe Delete doesn't have to return 204 to indicate a success?
> > 
> > So what are you all that have provided a HATEOAS API been doing?
> 
> Enjoy your travel towards the next hypermedia constraint[4] 'aha-moment'. It will surely come.
> 
> Jan
> 
> 
> > 
> > Thank you.
> > 
> 
> 
> [1] http://tech.groups.yahoo.com/group/rest-discuss/message/8377
> [2] http://www.nordsc.com/blog/?p=293#cbcID-tweak
> [3] http://www.opensearch.org
> [4] You see me hammering on the correct term as opposed to the acronym, don't you :-)
> 
> 
> 
> 
> > 
> > 
> > 
> 
> -----------------------------------
> Jan Algermissen, Consultant
> NORD Software Consulting
> 
> Mail: algermissen@...
> Blog: http://www.nordsc.com/blog/
> Work: http://www.nordsc.com/
> -----------------------------------
> 
> 
> 
> 
> 
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

On Feb 21, 2010, at 1:15 PM, malkarouri wrote:

> Hi everyone,
> 
> I have a functionality that I would like to describe in a REST fashion. Because it is effectively an idempotent transform of input to output, I would usually describe it as Resources with addresses like http://example.dom/transformed_result?input1=1&input2=y or some other equivalent URL scheme, and use GET.
> Except in this case, my input is a large text (csv) that can be passed as POST input rather than GET. What are my options?

Use POST. It is the more natural solution.

POST /transformer
Content-Type: text/csv

200 Ok
Content-Type: text/csv

[transformed output]

If you want to keep the output around onthe server, create a new resource and return 201 instead.

Jan

> The first thing that comes to mind is uploading the csv creating a new resource in the process and GETting another resource that holds the result of the transform. Only that I never need the created csv resource again and that it will be multiple HTTP requests for what warrants in my opinion a single one.
> 
> Any help is appreciated.
> 
> Regards,
> 
> Muhammad Alkarouri
> 
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Volume 4 of This week in REST is up on the REST wiki -
http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Feb_15_2010
and the blog - http://bit.ly/axW0Gn

For contributing links this week visit
http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Feb_22_2010

Enjoy!
Ivan

On Feb 22, 2010, at 10:03 AM, izuzak wrote:

> Volume 4 of This week in REST is up on the REST wiki -
> http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Feb_15_2010
> and the blog - http://bit.ly/axW0Gn
> 
> For contributing links this week visit
> http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Feb_22_2010
> 
> Enjoy!


Thanks! Keep up the good work.

Jan


> Ivan
> 
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Hello,

Alan Dean wrote:
> 
> Quite some time ago I wrote a little sample app, based mostly on an 
> article by Paul James [1] which was a simple digest auth implementation. 
> Now perhaps my memory has gone soggy, but I'm sure that there was a 
> workaround to avoid the annoying pop-up dialog being displayed 
> (something like you had to make sure that the response length was at 
> least 420 characters).
> 
> Well, I just ran the sample again and for the life of me I can't 
> suppress the dialog (in order to replace it with something prettier that 
> uses AJAX to carry out the actual auth handshake). Has there been fix 
> work done on recent browser versions to stop this end-around? If so (or 
> even if not, for that matter) does anyone have a way of doing it?
> 
> Thanks,
> Alan
> 
> [1] http://www.peej.co.uk/articles/http-auth-with-html-forms.html 
> <http://www.peej.co.uk/articles/http-auth-with-html-forms.html>

Are you trying to access the protected resource directly first? I 
suppose in this case, it will return a 401 status with a 
WWW-Authenticate header (basic or digest) which will trigger the browser 
popup anyway, unless the initial request with made with XMLHttpRequest 
AND with username/password (at least according to the draft spec [1], 
depending on its implementation status).


There's a point about this trick I'm not clear about: how to get the 
AJAX request to use Digest and not Basic auth?

The XMLHttpRequest draft spec is silent on this issue. If the 
authentication is pre-emptive (that is, if it's sent with the first 
request, not as a response to a 401/WWW-Authenticate challenge), which 
one is it meant to choose? It looks like it's Basic by default.

I guess a workaround for this would be to make two requests:
  C -> S: Request with something like like Basic null:null (like the 
logout function in Paul James's example service [2])
  S -> C: 401 with WWW-Authenticate Digest
  C -> S: another Ajax request with username:password, assuming that the 
browser's mechanism has retained the digest parameters sent by the 
previous response.

I can't really see how it's possible without an initial dummy request. 
You could try by sending the Authorization header via XHR manually, but 
(a) your server would need to support pre-emtive Digest authentication 
and (b) that username/password would need to integrate with the 
browser's Digest auth mechanism for subsequent requests.
I reckon the only way of doing (b) is to let the browser know the 
username and password the user typed in (perhaps via XHR, but again, XHR 
doesn't seem to let you specify Basic or Digest, pre-emptively at least).



(As a side-note, Paul James's example service returns a 401 status code 
without a WWW-Authenticate header when replying to a "logout" (via 
null:null) request, which isn't compliant with the HTTP spec; I guess 
it's just a small bug, since in principle, doing so shouldn't trigger a 
new popup box.)



Best wishes,

Bruno.



[1] http://www.w3.org/TR/XMLHttpRequest/#the-send-method
[2] http://www.peej.co.uk/sandbox/htmlhttpauth/index.html

Hi,

I have the following questions on the implementation of a REST API:

1.
I have a resource which can be used like:

  (a) GET resource/{id}

but it would be useful, to save round trips, to be able to invoke it with
several ids at once:

  (b) GET resource?id={id1}&id={id2}... or
        GET resource/ids;id1;id2... or
        GET resource/id1/id2... (BTW is this URL template acceptable? The
ids are not in a hierarchy as the slashes may suggest, but I've seen it used
elsewhere).

This falls in the realm of REST + batch operations but I don't know what is
the best solution according to the REST architectural style.
From what I've read some people are of the opinion that (a) should be used
with HTTP pipelining for batch operations while others think that the
solution (b) is
equally acceptable since this is a resource that happens to take multiple
query/path/matrix parameters.

2.
I have another resource which is an algorithm that takes as input:
- a list of parameters [x1, x2, ...]
- another list of parameters [y1, y2, ...]
- some other optional arguments

My initial attempt is very RPC-style since I just implemented a resource
that takes the input as:

  GET resource?x=x1&x=x2&...&y=y1&y=y2...&{rest of the optional arguments}

One possible solution is to define a resource that accepts a POST with a
representation of the input of the algorithm (say in JSON) and returns
the HTTP status code 201 and another resource which can be invoked with GET.
However this may complicate the server side implementation since I have to
maintain state and decide for how long will the resource created by the POST
be available, etc...
In fact, if all the client wants is to invoke an algorithm, why would he do
it in 2 steps instead of just one?  So this solution doesn't appeal to me
very much.

How can I make the resources 1. and 2. above RESTful?

Thanks,
Dário

I'm trying to implement a RESTful API. What happened if I have these following URLs:

1 - http://localhost/api/Product/1/Category
2 - http://localhost/api/Category/8

and this is the response in both cases:

   <category>
    <category-name>Category1</category-name>
    <created-at type="datetime">2010-02-15T15:38:30Z</created-at>
    <description>Category Description</description>
    <id type="integer">1</id>
    <updated-at type="datetime">2010-02-15T15:38:30Z</updated-at>
   </category>

Is it valid? If I have that case, Should I use Content-Location?, in order to show the alternatives URLs.

Thanks in advance.
Regards.

>>>>> "D�rio" == D�rio Abdulrehman <dario.rehman@...> writes:

    D�rio> but it would be useful, to save round trips, to be able to
    D�rio> invoke it with several ids at once:

I think what you should become clear about is: is this a resource?

It probably is. I.e. a subset of the results. So what you pass in is a
filter that identifies the subset.

So how you solve that is perhaps not so important. But it helps if you
come up with some URL for a subset/filter. Perhaps:

  /resource/subset/?id=1&id=2

So I think that fits in well.

Don't think that REST architectural style forces you to do weird
things like using POSTs to create such resources.

-- 
Cheers,

Berend de Boer

Hello Dario,

Just be careful with URI templates... remember to stick to as few entry
points as possible

The POST/201+GET solution makes sense but as Berend mentioned, not required.

Regards

Guilherme Silveira
Caelum | Ensino e Inova��o
http://www.caelum.com.br/


On Mon, Feb 22, 2010 at 3:32 PM, <berend@...> wrote:

>
>
> >>>>> "D�rio" == D�rio Abdulrehman <dario.rehman@...<dario.rehman%40gmail.com>>
> writes:
>
> D�rio> but it would be useful, to save round trips, to be able to
> D�rio> invoke it with several ids at once:
>
> I think what you should become clear about is: is this a resource?
>
> It probably is. I.e. a subset of the results. So what you pass in is a
> filter that identifies the subset.
>
> So how you solve that is perhaps not so important. But it helps if you
> come up with some URL for a subset/filter. Perhaps:
>
> /resource/subset/?id=1&id=2
>
> So I think that fits in well.
>
> Don't think that REST architectural style forces you to do weird
> things like using POSTs to create such resources.
>
> --
> Cheers,
>
> Berend de Boer
>  
>

Hello there,

You are right, a resource representation does not need to be uniquelly
mapped to a URI. The response header can be used to either redirect or give
the client a hint where to go to for the "original" one.

Regards

Guilherme Silveira
Caelum | Ensino e Inova��o
http://www.caelum.com.br/


On Mon, Feb 22, 2010 at 3:10 PM, cosme.perez82 <cosme.perez82@yahoo.com>wrote:

>
>
> I'm trying to implement a RESTful API. What happened if I have these
> following URLs:
>
> 1 - http://localhost/api/Product/1/Category
> 2 - http://localhost/api/Category/8
>
> and this is the response in both cases:
>
> <category>
> <category-name>Category1</category-name>
> <created-at type="datetime">2010-02-15T15:38:30Z</created-at>
> <description>Category Description</description>
> <id type="integer">1</id>
> <updated-at type="datetime">2010-02-15T15:38:30Z</updated-at>
> </category>
>
> Is it valid? If I have that case, Should I use Content-Location?, in order
> to show the alternatives URLs.
>
> Thanks in advance.
> Regards.
>
>  
>

One more question:

I understand that one of the principles of RESTful design is to return links
for other resources in the responses.

Let's say I have a resource A that returns a response which contains an idA.

I know that probably some users will be satisfied with idA but others will
want to get further information on idA by invoking another resource B.

From what I've read I have no question in my mind that the URI for resource
B/idA should be returned in the response for resource A.
However should I return also idA in that response to save a round trip for
the users that are satisfied with idA, like so (assuming a JSON media type):

{"name" "idA" "link" "GET /B/idA"}

or should I just return

{"link" "GET /B/idA"} ?

Thanks.

On Mon, Feb 22, 2010 at 6:41 PM, Guilherme Silveira <
guilherme.silveira@....br> wrote:

> Hello Dario,
>
> Just be careful with URI templates... remember to stick to as few entry
> points as possible
>
> The POST/201+GET solution makes sense but as Berend mentioned, not
> required.
>
>
> Regards
>
> Guilherme Silveira
> Caelum | Ensino e Inovação
> http://www.caelum.com.br/
>
>
> On Mon, Feb 22, 2010 at 3:32 PM, <berend@...> wrote:
>
>>
>>
>> >>>>> "Dário" == Dário Abdulrehman <dario.rehman@...<dario.rehman%40gmail.com>>
>> writes:
>>
>> Dário> but it would be useful, to save round trips, to be able to
>> Dário> invoke it with several ids at once:
>>
>> I think what you should become clear about is: is this a resource?
>>
>> It probably is. I.e. a subset of the results. So what you pass in is a
>> filter that identifies the subset.
>>
>> So how you solve that is perhaps not so important. But it helps if you
>> come up with some URL for a subset/filter. Perhaps:
>>
>> /resource/subset/?id=1&id=2
>>
>> So I think that fits in well.
>>
>> Don't think that REST architectural style forces you to do weird
>> things like using POSTs to create such resources.
>>
>> --
>> Cheers,
>>
>> Berend de Boer
>>  
>>
>
>

>
>
> In reality of course, this shouldn't really necessitate multiple calls to
> the server if called multiple times since previous results have been cached
> and processed on the client side. Only when the cache expires, should there
> be an attempt to request again. I'm not really sure if RESTful clients that
> respect HATEOAS do it this way, and should they in the first place. If they
> do, are there tools that exist for this?
>

It is quite unnecessary to treat this as a client problem, whether the
system is hypertext based or not. If there is a cache in the reverse proxy
on the server side, all the interactions will be seamless to the client. If
there is a forward proxy cache on the client network, it will cut down the
requests based on the expiry/invalidation policies set by the server or
configured in the cache.

BUT, please note that, chaining calls like this is not a good idea since it
performs poorly when the caches are cold.

Subbu

D�rio,

On Feb 22, 2010, at 6:13 PM, D�rio Abdulrehman wrote:

> 
> 
> Hi,
> 
> I have the following questions on the implementation of a REST API:
> 
> 1.
> I have a resource which can be used like:
> 
>   (a) GET resource/{id} 
> 
> but it would be useful, to save round trips,

Can you explain what the scenario is? It is not a primary goal to save round trips. IOW, just because you can does not mean you should (save round trips).


> to be able to invoke it with several ids at once:
> 
>   (b) GET resource?id={id1}&id={id2}... or
>         GET resource/ids;id1;id2... or 
>         GET resource/id1/id2... (BTW is this URL template acceptable? The ids are not in a hierarchy as the slashes may suggest, but I've seen it used elsewhere).
> 

Use the first one: GET resource?id={id1}&id={id2}.

> This falls in the realm of REST + batch operations but I don't know what is the best solution according to the REST architectural style.

If you really have to do this, the RESTful way is to make a resource that has the semantics of the "bag" (like you did). But beware that the response is a representation of *that* resource.

You might want to look at multipart messages for this. Here is a related experimental I-D:
http://tools.ietf.org/html/draft-snell-http-batch-01


> From what I've read some people are of the opinion that (a) should be used with HTTP pipelining for batch operations while others think that the solution (b) is
> equally acceptable since this is a resource that happens to take multiple query/path/matrix parameters.

HTTP pipelining is not yet a reality, but theoretically, it would a the preferable solution as opposed to a batch retrievel. You batch would not be visible to caches for example.


> 
> 2.
> I have another resource which is an algorithm that takes as input:
> - a list of parameters [x1, x2, ...]
> - another list of parameters [y1, y2, ...]
> - some other optional arguments
> 
> My initial attempt is very RPC-style since I just implemented a resource that takes the input as:
> 
>   GET resource?x=x1&x=x2&...&y=y1&y=y2...&{rest of the optional arguments}

That is not RPC-style. I see nothing unRESTful in it.


> 
> One possible solution is to define a resource that accepts a POST with a representation of the input of the algorithm (say in JSON) and returns
> the HTTP status code 201 and another resource which can be invoked with GET.

This only makes sense if you want to persist the result as a resource. And if you do, use 201, Location and Content-Location so the client does not need the extra GET.

> However this may complicate the server side implementation since I have to maintain state and decide for how long will the resource created by the POST be available, etc...

Yes. If you do not need it, don't do it. The GET is fine.

Jan


> In fact, if all the client wants is to invoke an algorithm, why would he do it in 2 steps instead of just one?  So this solution doesn't appeal to me very much.
> 
> How can I make the resources 1. and 2. above RESTful?




> 
> Thanks,
> D�rio
> 
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Jan Algermissen wrote:
> 
> Use the first one: GET resource?id={id1}&id={id2}.
> 

At the risk of being smacked down by Roy again on URI opacity, I point
out that generic URI parsers will return 'id=id2' when presented with
two separate values for the 'id' parameter...

> 
> >   GET resource?x=x1&x=x2&...&y=y1&y=y2...&{rest of the optional
> > arguments}
> 
> That is not RPC-style. I see nothing unRESTful in it.
> 

It's a "Matrix URI", as per:

http://www.w3.org/DesignIssues/MatrixURIs.html

I've experimented with this notion, there are plenty of drawbacks to
such a URI allocation scheme, however.  The question for Dario is
whether his system can use fragment URIs to achieve the same result.

TBL's design note suggests using Matrix URIs for latitude, longitude
and scale for a map, as an example.  SVG implements coordinates and
scale using a fragment URI syntax.  Something to consider.

-Eric

On Feb 23, 2010, at 8:49 AM, Eric J. Bowman wrote:

> Jan Algermissen wrote:
>> 
>> Use the first one: GET resource?id={id1}&id={id2}.
>> 
> 
> At the risk of being smacked down by Roy again on URI opacity, I point
> out that generic URI parsers will return 'id=id2' when presented with
> two separate values for the 'id' parameter...

No, there can be multiple parameters with the same name. The value is being returned as a list.

> 
>> 
>>>  GET resource?x=x1&x=x2&...&y=y1&y=y2...&{rest of the optional
>>> arguments}
>> 
>> That is not RPC-style. I see nothing unRESTful in it.
>> 
> 
> It's a "Matrix URI", as per:
> 
> http://www.w3.org/DesignIssues/MatrixURIs.html
> 
> I've experimented with this notion, there are plenty of drawbacks to
> such a URI allocation scheme, however.  The question for Dario is
> whether his system can use fragment URIs to achieve the same result.

Do you mean URIs with fragment identifiers?

If so: no because the fragment is not being sent to the server.

Jan



> 
> TBL's design note suggests using Matrix URIs for latitude, longitude
> and scale for a map, as an example.  SVG implements coordinates and
> scale using a fragment URI syntax.  Something to consider.
> 
> -Eric

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

On Mon, Feb 22, 2010 at 11:15 PM, Jan Algermissen
<algermissen1971@...>wrote:

> On Feb 22, 2010, at 6:13 PM, D�rio Abdulrehman wrote:
> ...
>
> > to be able to invoke it with several ids at once:
> >
> > (b) GET resource?id={id1}&id={id2}... or
> > GET resource/ids;id1;id2... or
> > GET resource/id1/id2... (BTW is this URL template acceptable? The ids are
> not in a hierarchy as the slashes may suggest, but I've seen it used
> elsewhere).
> >
>
> Use the first one: GET resource?id={id1}&id={id2}.
>
>
> > This falls in the realm of REST + batch operations but I don't know what
> is the best solution according to the REST architectural style.
>
> If you really have to do this, the RESTful way is to make a resource that
> has the semantics of the "bag" (like you did). But beware that the response
> is a representation of *that* resource.
>
> You might want to look at multipart messages for this. Here is a related
> experimental I-D:
> http://tools.ietf.org/html/draft-snell-http-batch-01
>
>
>
Another complexity to consider is, what happens if id1 is a valid identifier
and id2 is not?  If you were just GETting id2, the answer would be obvious
... return a 404.  But now I need to return multiple statuses (200 for id1
and 404 for id2).  Hmm ...

WebDAV deals with this by returning a "multi-status response" and making the
client go through the contortions of interpreting all the response statuses
and matching them up to the original requests.  It is technically feasible,
but this is one of the reasons you don't see a very large number of people
writing WebDAV clients :-).

I would tend to think of your use case more as a "search" rather than a
"batch GET".  Think about defining a resource representing the collection of
all your resources, and use query parameters as filter expressions to limit
the results.  One advantage of this approach is you are no longer limited to
just filtering based on the identifier ... you could select on other values
as well.  And, maybe even throw in support for interpreting an "order by"
parameter for sorting, and maybe even "offset" and "limit" for pagination.

If you like the search paradigm, I would also suggest considering the Open
Search API (http://opensearch.org) as an alternative to rolling your own
approach.

Craig McClanahan

Jan Algermissen wrote:
> 
> Do you mean URIs with fragment identifiers?
> 
> If so: no because the fragment is not being sent to the server.
> 

How do we know that the query needs to go to the server?  We have no
notion of "resource" going here, media types haven't been considered,
so how can we jump right into designing a URI allocation scheme...?

(More to follow shortly, this thread needs hijacking.)

-Eric

On Feb 23, 2010, at 9:28 AM, Eric J. Bowman wrote:

> Jan Algermissen wrote:
>> 
>> Do you mean URIs with fragment identifiers?
>> 
>> If so: no because the fragment is not being sent to the server.
>> 
> 
> How do we know that the query needs to go to the server?  

What do you mean? Should the whole collection go to the client before making the selection?

Jan

> We have no
> notion of "resource" going here, media types haven't been considered,
> so how can we jump right into designing a URI allocation scheme...?
> 
> (More to follow shortly, this thread needs hijacking.)
> 
> -Eric

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

D�rio Abdulrehman wrote:
>
> Hi,
> 
> I have the following questions on the implementation of a REST API:
> 

Hi D�rio.  Please don't take my hijacking your thread personally, this
goes to a larger point I've been trying to make of late, that the
starting place is resource modeling, not implementation (URI design).
I'm not criticizing you (or anyone else) or singling you (or anyone
else) out, just tilting at the windmill of changing how REST is taught.

Today, I'm trying to illustrate my point by considering fragment vs.
query string.

>
> 1.
> I have a resource which can be used like:
> 
>   (a) GET resource/{id}
> 

Let's try to model that, first of all, by calling it a collection of
resources with unique IDs, '/collection/{member}' is widely understood.
But at this point I know of no reason it can't be /collection#member.

>
> but it would be useful, to save round trips, to be able to invoke it
> with several ids at once:
> 
>   (b) GET resource?id={id1}&id={id2}... or
>         GET resource/ids;id1;id2... or
>         GET resource/id1/id2... (BTW is this URL template acceptable?
> The ids are not in a hierarchy as the slashes may suggest, but I've
> seen it used elsewhere).
> 

This is where I get worried every time someone new posts exactly this
sort of question here.  We all know how pervasive misconceptions of
REST are.  We shouldn't play along with questions regarding URI design
without having any notion of what the resource is.

I'd love to go into resources/subresources and URI syntax, Xpointer,
and other solutions to this -- except I think this would push the thread
starter further along in the wrong direction.  I can't tell, because I
don't understand his notion of this resource.

>
> This falls in the realm of REST + batch operations...
>

I don't have enough information about the nature of the resource in
question, to know if that's an accurate assessment.  As Jan pointed
out, saving round trips isn't a goal of REST API design.  A RESTful API
will be conducive to caching, the side effect of which is saving round
trips.

Without some notion of the nature of the resource, it's impossible to
proceed in a disciplined fashion.  Can the data be modeled as SVG, and
if so, can SVG's fragment syntax be utilized to extract subresources
for display?  If not, is this a "lightbulb" for developing a new media
type with its own fragment syntax?

>
> From what I've read some people are of the opinion that (a) should be
> used with HTTP pipelining for batch operations while others think
> that the solution (b) is
> equally acceptable since this is a resource that happens to take
> multiple query/path/matrix parameters.
> 

The opinions of others is a bad place to learn REST.  Roy's thesis has
some nuggets of wisdom in it, though...

"
A distributed hypermedia architect has only three fundamental options:
1) render the data where it is located and send a fixed-format image to
the recipient; 2) encapsulate the data with a rendering engine and send
both to the recipient; or, 3) send the raw data to the recipient along
with metadata that describes the data type, so that the recipient can
choose their own rendering engine.
"

Since we have no notion of "resource" to ground us here, we lack the
ability to choose one of these options.  If SVG or some SVG-like
fragment implementation within a media type isn't the solution, then
perhaps approximating the mobile object style by applying the optional
Code on Demand constraint (2) is called for.  In which case, parameters
may not show up in the URI at all, query or fragment (still REST).

Resources must be conceptually modeled before any decisions about
system architecture may be effectively made.  Craig's response was
sound advice, but rests on an assumption that the resource models out
as something that can be represented as OpenSearch.  But, the resource
may not fit that model -- who's to say, from the information we've been
given?

I would suggest that if the purpose is to submit some JSON code to a
resource, then make that code a query string and GET the response
(Craig's right, POST isn't correct), saving a round-trip and enabling
caching.  But I have no idea if this is appropriate, vs. using some URI
fragment syntax, since we haven't modeled the resource or considered
any media types, or discussed architectural options like CoD.

I'm up on my high horse on this, because I think when we REST sempai
start winging it by throwing URI patterns around, we only add to the
confusion of the REST kohai by reinforcing whatever misconceptions led
them to design an API by starting with URI allocation scheme in the
first place.  Meaning no offense to anyone, I'm guilty of same.

>
> 2.
> I have another resource which is an algorithm that takes as input:
> - a list of parameters [x1, x2, ...]
> - another list of parameters [y1, y2, ...]
> - some other optional arguments
> 

Let's try to model that resource, first of all, by calling it a service
endpoint.  Then we can get down to the brass tacks of implementation.

> 
> How can I make the resources 1. and 2. above RESTful?
> 

I have no idea.  Even if I did have a better idea of the nature of
these resources, REST is concerned with the interaction between
components in a system via Uniform Connector Interfaces.  Analyzing one
resource in isolation won't usually tell you anything about whether the
system is RESTful or not, any more than looking at its URI can.

I can help you model your resources, determine their relations to one
another, and express that using hypertext link relations.  I can help
with the selection and/or design of media types.  I can help develop an
architecture around those media types and link relations.  I can help
design a hypertext engine to drive application state.

What I can't do, is wave my magic guru wand and come up with a URI
allocation scheme describing what methods to use on what resources of
interest, and call it a REST API.  I can only develop a REST API *after*
I know the nature of the resources involved, otherwise I'd just be
guessing.

REST development is all about tradeoffs.  Disciplined REST development
is based on weighing the pros and cons of architectural choices.
Coming up with a RESTful solution without considering choices and
weighing tradeoffs is possible, but how is the architect then to
evaluate his or her creation against the goals for the system?

Starting with URI design locks the architect into a set of fundamental
design constraints which may be inappropriate for the system.  The
choice between query string and URI fragment places a rigid dividing
line between client and server that's difficult, if not impossible, to
change further on down the road.

-Eric

Jan Algermissen wrote:
> 
> On Feb 23, 2010, at 9:28 AM, Eric J. Bowman wrote:
> 
> > Jan Algermissen wrote:
> >> 
> >> Do you mean URIs with fragment identifiers?
> >> 
> >> If so: no because the fragment is not being sent to the server.
> >> 
> > 
> > How do we know that the query needs to go to the server?  
> 
> What do you mean? Should the whole collection go to the client before
> making the selection?
> 

If that architectural choice best fits the goals of the system, then
yes.  Either choice may be RESTful, one is not more RESTful than the
other.

The point of applied software architecture, following any given style,
is to provide a context for making implementation decisions.  Media
type design impacts URI design in REST.  Media type selection/creation
does not follow from URI design -- the cart must come *before* the
horse.

Restricting media type choice based on what works with the URI design,
instead of choosing/creating the media type which best fits the data
model, breaks with REST discipline.  The resulting system can only be
compared against its own narrow interpretation of REST, which defeats
the purpose of applied software architecture.

Ideally, the architect can evaluate the implementation's design choices
against the entire REST style, as opposed to a preconceived notion of
the style -- where queries must be made against the server, and the pros
and cons of constraining query to the client through use of URI
fragments are not considered.  (No offense intended, just illustrating 
my point.)

To follow REST, is to use it as your guide when considering tradeoffs,
like where to draw the line between client (#) and server (?) when
modeling a new API.  Being RESTful is not the end-all, be-all of API
design -- meeting the goals of the system, is (RESTful or not).

One API may not be more RESTful than another, but only one likely fits
best with the goals of the system.  REST is a process, not an outcome.

-Eric

"Eric J. Bowman" wrote:
>
> the cart must come *before* the
> horse.
> 

Wait... that isn't right!  Crap.

-Eric

On Feb 23, 2010, at 1:38 PM, Subbu Allamaraju wrote:

> 
> In reality of course, this shouldn't really necessitate multiple calls to the server if called multiple times since previous results have been cached and processed on the client side. Only when the cache expires, should there be an attempt to request again. I'm not really sure if RESTful clients that respect HATEOAS do it this way, and should they in the first place. If they do, are there tools that exist for this?
> 
> It is quite unnecessary to treat this as a client problem, whether the system is hypertext based or not. If there is a cache in the reverse proxy on the server side, all the interactions will be seamless to the client. If there is a forward proxy cache on the client network, it will cut down the requests based on the expiry/invalidation policies set by the server or configured in the cache.
> 
> BUT, please note that, chaining calls like this is not a good idea since it performs poorly when the caches are cold.
> 

Hm, but the cache expiry states up to when the the resource is valid. Sure, chaining calls would perform poorly when the server doesn't instruct the client on how long the results are valid. But, for well-designed REST services, I believe it should be alright. Please let me know if I should think otherwise.

How else would one go about accessing resources using HATEOAS though? Assuming moreover that the end application can't provide a web-like interface.

> Subbu
> 

Jan Vincent Liwanag
jvliwanag@...

On Tue, Feb 23, 2010 at 10:37 AM, Eric J. Bowman <eric@...>wrote:

> Dário Abdulrehman wrote:
> >
> > Hi,
> >
> > I have the following questions on the implementation of a REST API:
> >
>
> Hi Dário.  Please don't take my hijacking your thread personally, this
> goes to a larger point I've been trying to make of late, that the
> starting place is resource modeling, not implementation (URI design).
> I'm not criticizing you (or anyone else) or singling you (or anyone
> else) out, just tilting at the windmill of changing how REST is taught.
>
> Today, I'm trying to illustrate my point by considering fragment vs.
> query string.
>
> >
> > 1.
> > I have a resource which can be used like:
> >
> >   (a) GET resource/{id}
> >
>
> Let's try to model that, first of all, by calling it a collection of
> resources with unique IDs, '/collection/{member}' is widely understood.
> But at this point I know of no reason it can't be /collection#member.
>

I will provide details about the domain I'm working on:
I have a database with biological data: proteins, genes, regulations, etc.,
and the REST API I would like to design gives access to those resources for
querying.
Since the types of queries I want to provide are very restricted I don't
think it fits the OpenSearch model suggested by Craig.

So, the example (a) I gave previously could be instantiated for the case of
proteins and genes.
A protein/gene is identified by its name but it has other interesting data
associated (description, aminoacid sequence, etc.), so I would like to model
it as a resource that responds to GET, returning a media type with that
information.

GET /protein/{id}    =>    Returns media type (JSON for example) with
description, aminoacid sequence, etc.

Mutatis mutandis for gene.


> >
> > but it would be useful, to save round trips, to be able to invoke it
> > with several ids at once:
> >
> >   (b) GET resource?id={id1}&id={id2}... or
> >         GET resource/ids;id1;id2... or
> >         GET resource/id1/id2... (BTW is this URL template acceptable?
> > The ids are not in a hierarchy as the slashes may suggest, but I've
> > seen it used elsewhere).
> >
>
> This is where I get worried every time someone new posts exactly this
> sort of question here.  We all know how pervasive misconceptions of
> REST are.  We shouldn't play along with questions regarding URI design
> without having any notion of what the resource is.
>
> I'd love to go into resources/subresources and URI syntax, Xpointer,
> and other solutions to this -- except I think this would push the thread
> starter further along in the wrong direction.  I can't tell, because I
> don't understand his notion of this resource.
>

> >
> > This falls in the realm of REST + batch operations...
> >
>
> I don't have enough information about the nature of the resource in
> question, to know if that's an accurate assessment.  As Jan pointed
> out, saving round trips isn't a goal of REST API design.  A RESTful API
> will be conducive to caching, the side effect of which is saving round
> trips.
>
> Without some notion of the nature of the resource, it's impossible to
> proceed in a disciplined fashion.  Can the data be modeled as SVG, and
> if so, can SVG's fragment syntax be utilized to extract subresources
> for display?  If not, is this a "lightbulb" for developing a new media
> type with its own fragment syntax?
>


Given the above description of the resources does it still make sense to
provide the batch version of the resource?
I see the users wanting to GET information about a list of proteins/genes
and it would certainly be useful to do it batch style.



>
> >
> > From what I've read some people are of the opinion that (a) should be
> > used with HTTP pipelining for batch operations while others think
> > that the solution (b) is
> > equally acceptable since this is a resource that happens to take
> > multiple query/path/matrix parameters.
> >
>
> The opinions of others is a bad place to learn REST.  Roy's thesis has
> some nuggets of wisdom in it, though...
>
> "
> A distributed hypermedia architect has only three fundamental options:
> 1) render the data where it is located and send a fixed-format image to
> the recipient; 2) encapsulate the data with a rendering engine and send
> both to the recipient; or, 3) send the raw data to the recipient along
> with metadata that describes the data type, so that the recipient can
> choose their own rendering engine.
> "
>
> Since we have no notion of "resource" to ground us here, we lack the
> ability to choose one of these options.  If SVG or some SVG-like
> fragment implementation within a media type isn't the solution, then
> perhaps approximating the mobile object style by applying the optional
> Code on Demand constraint (2) is called for.  In which case, parameters
> may not show up in the URI at all, query or fragment (still REST).
>
> Resources must be conceptually modeled before any decisions about
> system architecture may be effectively made.  Craig's response was
> sound advice, but rests on an assumption that the resource models out
> as something that can be represented as OpenSearch.  But, the resource
> may not fit that model -- who's to say, from the information we've been
> given?
>
> I would suggest that if the purpose is to submit some JSON code to a
> resource, then make that code a query string and GET the response
> (Craig's right, POST isn't correct), saving a round-trip and enabling
> caching.  But I have no idea if this is appropriate, vs. using some URI
> fragment syntax, since we haven't modeled the resource or considered
> any media types, or discussed architectural options like CoD.
>
> I'm up on my high horse on this, because I think when we REST sempai
> start winging it by throwing URI patterns around, we only add to the
> confusion of the REST kohai by reinforcing whatever misconceptions led
> them to design an API by starting with URI allocation scheme in the
> first place.  Meaning no offense to anyone, I'm guilty of same.
>
> >
> > 2.
> > I have another resource which is an algorithm that takes as input:
> > - a list of parameters [x1, x2, ...]
> > - another list of parameters [y1, y2, ...]
> > - some other optional arguments
> >
>
> Let's try to model that resource, first of all, by calling it a service
> endpoint.  Then we can get down to the brass tacks of implementation.
>


This resource is an algorithm that takes as input lists of proteins, genes
and some other parameters and outputs the results.


>
> >
> > How can I make the resources 1. and 2. above RESTful?
> >
>
> I have no idea.  Even if I did have a better idea of the nature of
> these resources, REST is concerned with the interaction between
> components in a system via Uniform Connector Interfaces.  Analyzing one
> resource in isolation won't usually tell you anything about whether the
> system is RESTful or not, any more than looking at its URI can.
>
> I can help you model your resources, determine their relations to one
> another, and express that using hypertext link relations.  I can help
> with the selection and/or design of media types.  I can help develop an
> architecture around those media types and link relations.  I can help
> design a hypertext engine to drive application state.
>
> What I can't do, is wave my magic guru wand and come up with a URI
> allocation scheme describing what methods to use on what resources of
> interest, and call it a REST API.  I can only develop a REST API *after*
> I know the nature of the resources involved, otherwise I'd just be
> guessing.
>
> REST development is all about tradeoffs.  Disciplined REST development
> is based on weighing the pros and cons of architectural choices.
> Coming up with a RESTful solution without considering choices and
> weighing tradeoffs is possible, but how is the architect then to
> evaluate his or her creation against the goals for the system?
>
> Starting with URI design locks the architect into a set of fundamental
> design constraints which may be inappropriate for the system.  The
> choice between query string and URI fragment places a rigid dividing
> line between client and server that's difficult, if not impossible, to
> change further on down the road.
>

Given the nature of the resources I hope it should now be easier to design a
URI scheme.

Thanks.


>
> -Eric
>

When designing media type(s) for a domain that includes a family of "business document types" (such as Atom does with feed and entry or such as UBL does with catalogue, order, invoice,...) what are the pros and cons of 

1. Defining one 'big' media type encompassing all documents

2. Defining many media types that correspond to the individual "business document types"



Personally, I favor the 'one big media type' ecause I like the type to in a sense identify the domain and to subsum all the processing rules involved. OTH, it causes real dispatching pains because you do not know what you have before you poke into the body.

I usually address that with the use of a profile parameter in conneg, for example: Accept: application/mydomain;profile=doctypeA[1]. Servers the know the client's preferences and can send the doctypeA (without the need to put the profile parameter on the ContentType header (where it might get stripped my interediaries anyhow).

However, frameworks seem to be bad at that kind of conneg at the moment, hence this posting :-)


Any thoughts or insights?

Jan

[1] This works also well with client driven conneg, as in <link href="" rel="" type="application/mydomain;profile=doctypeA"/>

Jan:

I, too, prefer a large-grained media-type (application level and higher).

When you say "...It causes real dispatching pains because you do not
know what you have before you poke into the body."  are you referring
to dispatch issues on the client? server?

There are a number of factors in designing a media-type. For example,
I think over-specifying the document structure can make implementing
state-machines against the media-type difficult.

Recently, I've been copying the HTML document structure ((html = head
+ body) when creating my application-level media types. For example,
one large app I'm working on has the following media-type structure:

<root>
<system /> <!-- system-level meta data and other control values
including general links -->
<data /> <!-- request-specific data including any lists, item details, etc. -->
</root>

It's then up to the client and server to understand the details of the
<system> and <data> sections such as <user-list /> or <user-details />
or <list class="users" /> depending on your approach.

mca
http://amundsen.com/blog/




On Tue, Feb 23, 2010 at 12:40, Jan Algermissen <algermissen1971@...> wrote:
> When designing media type(s) for a domain that includes a family of "business document types" (such as Atom does with feed and entry or such as UBL does with catalogue, order, invoice,...) what are the pros and cons of
>
> 1. Defining one 'big' media type encompassing all documents
>
> 2. Defining many media types that correspond to the individual "business document types"
>
>
>
> Personally, I favor the 'one big media type' ecause I like the type to in a sense identify the domain and to subsum all the processing rules involved. OTH, it causes real dispatching pains because you do not know what you have before you poke into the body.
>
> I usually address that with the use of a profile parameter in conneg, for example: Accept: application/mydomain;profile=doctypeA[1]. Servers the know the client's preferences and can send the doctypeA (without the need to put the profile parameter on the ContentType header (where it might get stripped my interediaries anyhow).
>
> However, frameworks seem to be bad at that kind of conneg at the moment, hence this posting :-)
>
>
> Any thoughts or insights?
>
> Jan
>
> [1] This works also well with client driven conneg, as in <link href="" rel="" type="application/mydomain;profile=doctypeA"/>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
 


On 2/20/2010 11:16 AM, Markus KARG wrote:
> 
>
> > > As Roy Fielding pointed out several times, an API must not call
> > itself RESTful as long as it is not applying HATEOAS. I want to
> support
> > this constraint by adding HATEOASfulness to my future
> applications. One
> > thing I just do not understand so far about HATEOAS-via-HTTP is (and
> > what other people asked me when citing Fielding in this issue): How a
> > client shall actually know which http method to use to follow a link
> > received with the previous request to a RESTful server? Roy
> answered in
> > his blog that the method could be read out of the last result. But
> > actually how?
> >
> > This information is part of the hypermedia semantics specified (media
> > type specification or link relation specification etc). Such a
> > specification can either explicitly state the method to use (see RFC
> > 5023 for example) or specify a hypermedia element that tells the
> client
> > at runtime what method to use (e.g. HTML forms).
>
> I understand that with AtomPub RFC5023 specifies that. Call me dumb, but
> what to do if I am not using AtomPub but self-made service (like a
> web shop
> application)? How to do it then? For example, if I am writing a web
> shop, an
> that one allows to place an order using a POST. How to tell a client
> that it
> shall use that POST? I mean, *where* to put that information in a
> technical
> sense?
>
As Jan pointed it out, understanding navigation is media driven. In
the JSON media realm, you can use JSON Schema to generically instruct
a user agent how to navigate different JSON data structures (which may
represent different sub-media types). You can write a JSON Schema that
describes your data:

{
   name: "Order",
   links: [
     rel: "create",
     href: "/create_order",
     method: "POST"
   ],
   properties: {
      ...
   }
}

Thanks,

- -- 
Kris Zyp
SitePen
(503) 806-1841
http://sitepen.com

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
 
iEYEARECAAYFAkuEHHAACgkQ9VpNnHc4zAxU/gCglAiCEHugG0VNZWl1HfRlnpzj
vz0An3k8UcK4f4oivLTjKEt49Imn0p3A
=S5pq
-----END PGP SIGNATURE-----

Personally, I think that that should not only be one big domain-specific
media type, but actually I would love to see a global standard for any type
of machine-readable business document, just like HTML for humans. Dublin
Core is going in the right direction by standardizing things globally, but
it is not global enough. Also I see interesting relations to semantic
solutions like RDF.

But in short term, I do not see such a global solution, so there might be a
need to live with "small" media types meanwhile.

> -----Original Message-----
> From: rest-discuss@yahoogroups.com [mailto:rest-
> discuss@yahoogroups.com] On Behalf Of Jan Algermissen
> Sent: Dienstag, 23. Februar 2010 18:40
> To: REST Discuss
> Subject: [rest-discuss] Media Types: application/mydomain vs
> application/mydomain.doctypeA, application/mydomain.doctypeB,
> application/mydomain.doctypeC
> 
> When designing media type(s) for a domain that includes a family of
> "business document types" (such as Atom does with feed and entry or
> such as UBL does with catalogue, order, invoice,...) what are the pros
> and cons of
> 
> 1. Defining one 'big' media type encompassing all documents
> 
> 2. Defining many media types that correspond to the individual
> "business document types"
> 
> 
> 
> Personally, I favor the 'one big media type' ecause I like the type to
> in a sense identify the domain and to subsum all the processing rules
> involved. OTH, it causes real dispatching pains because you do not know
> what you have before you poke into the body.
> 
> I usually address that with the use of a profile parameter in conneg,
> for example: Accept: application/mydomain;profile=doctypeA[1]. Servers
> the know the client's preferences and can send the doctypeA (without
> the need to put the profile parameter on the ContentType header (where
> it might get stripped my interediaries anyhow).
> 
> However, frameworks seem to be bad at that kind of conneg at the
> moment, hence this posting :-)
> 
> 
> Any thoughts or insights?
> 
> Jan
> 
> [1] This works also well with client driven conneg, as in <link href=""
> rel="" type="application/mydomain;profile=doctypeA"/>
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

Kris,

 

this is interesting! As I am working with XSL / XML a lot, I did not take
such a deep look at JSON. Is that type of link support native to JSON or is
that just a specific use of JSON?

 

Thanks

Markus

 

From: Kris Zyp [mailto:kris@...] 
Sent: Dienstag, 23. Februar 2010 19:21
To: Markus KARG
Cc: 'Jan Algermissen'; 'REST Discuss'
Subject: Re: [rest-discuss] Re: [Jersey] Moved thread to rest-discuss /
HATEOAS-via-HTTP: Which HTTP Method to use to follow link?

 

-----BEGIN PGP SIGNED MESSAGE----- 
Hash: SHA1 
 


On 2/20/2010 11:16 AM, Markus KARG wrote:
>  



>



> > > As Roy Fielding pointed out several times, an API must

not call



> > itself RESTful as long as it is not applying HATEOAS. I

want to



> support



> > this constraint by adding HATEOASfulness to my future



> applications. One



> > thing I just do not understand so far about

HATEOAS-via-HTTP is (and



> > what other people asked me when citing Fielding in this

issue): How a



> > client shall actually know which http method to use to

follow a link



> > received with the previous request to a RESTful server? Roy



> answered in



> > his blog that the method could be read out of the last

result. But



> > actually how?



> >



> > This information is part of the hypermedia semantics

specified (media



> > type specification or link relation specification etc).

Such a



> > specification can either explicitly state the method to use

(see RFC



> > 5023 for example) or specify a hypermedia element that

tells the



> client



> > at runtime what method to use (e.g. HTML forms).



>



> I understand that with AtomPub RFC5023 specifies that. Call me

dumb, but



> what to do if I am not using AtomPub but self-made service (like

a



> web shop



> application)? How to do it then? For example, if I am writing a

web



> shop, an



> that one allows to place an order using a POST. How to tell a

client



> that it



> shall use that POST? I mean, *where* to put that information in a



> technical



> sense?



>
As Jan pointed it out, understanding navigation is media driven. In
the JSON media realm, you can use JSON Schema to generically instruct
a user agent how to navigate different JSON data structures (which may
represent different sub-media types). You can write a JSON Schema that
describes your data:

{
   name: "Order",
   links: [
     rel: "create",
     href: "/create_order",
     method: "POST"
   ],
   properties: {
      ...
   }
}

Thanks,

- -- 
Kris Zyp
SitePen
(503) 806-1841
http://sitepen.com

-----BEGIN PGP SIGNATURE----- 
Version: GnuPG v1.4.9 (MingW32) 
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ 
 
iEYEARECAAYFAkuEHHAACgkQ9VpNnHc4zAxU/gCglAiCEHugG0VNZWl1HfRlnpzj 
vz0An3k8UcK4f4oivLTjKEt49Imn0p3A 
=S5pq 
-----END PGP SIGNATURE----- 

I wonder whether the outline type of link description is actually RESTful: I
mean, "create order" clearly is a command, and such is not document driven
but method driven, which in turn looks like RPC to me?

 

From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com] On
Behalf Of Kris Zyp
Sent: Dienstag, 23. Februar 2010 19:21
To: Markus KARG
Cc: 'Jan Algermissen'; 'REST Discuss'
Subject: Re: [rest-discuss] Re: [Jersey] Moved thread to rest-discuss /
HATEOAS-via-HTTP: Which HTTP Method to use to follow link?

 



-----BEGIN PGP SIGNED MESSAGE----- 
Hash: SHA1 
 


On 2/20/2010 11:16 AM, Markus KARG wrote:
>  



>



> > > As Roy Fielding pointed out several times, an API must

not call



> > itself RESTful as long as it is not applying HATEOAS. I

want to



> support



> > this constraint by adding HATEOASfulness to my future



> applications. One



> > thing I just do not understand so far about

HATEOAS-via-HTTP is (and



> > what other people asked me when citing Fielding in this

issue): How a



> > client shall actually know which http method to use to

follow a link



> > received with the previous request to a RESTful server? Roy



> answered in



> > his blog that the method could be read out of the last

result. But



> > actually how?



> >



> > This information is part of the hypermedia semantics

specified (media



> > type specification or link relation specification etc).

Such a



> > specification can either explicitly state the method to use

(see RFC



> > 5023 for example) or specify a hypermedia element that

tells the



> client



> > at runtime what method to use (e.g. HTML forms).



>



> I understand that with AtomPub RFC5023 specifies that. Call me

dumb, but



> what to do if I am not using AtomPub but self-made service (like

a



> web shop



> application)? How to do it then? For example, if I am writing a

web



> shop, an



> that one allows to place an order using a POST. How to tell a

client



> that it



> shall use that POST? I mean, *where* to put that information in a



> technical



> sense?



>
As Jan pointed it out, understanding navigation is media driven. In
the JSON media realm, you can use JSON Schema to generically instruct
a user agent how to navigate different JSON data structures (which may
represent different sub-media types). You can write a JSON Schema that
describes your data:

{
   name: "Order",
   links: [
     rel: "create",
     href: "/create_order",
     method: "POST"
   ],
   properties: {
      ...
   }
}

Thanks,

- -- 
Kris Zyp
SitePen
(503) 806-1841
http://sitepen.com

-----BEGIN PGP SIGNATURE----- 
Version: GnuPG v1.4.9 (MingW32) 
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ 
 
iEYEARECAAYFAkuEHHAACgkQ9VpNnHc4zAxU/gCglAiCEHugG0VNZWl1HfRlnpzj 
vz0An3k8UcK4f4oivLTjKEt49Imn0p3A 
=S5pq 
-----END PGP SIGNATURE----- 

<snip>
Yes, that is usually good. However, I also think it is sometimes
confusing because you have the HTTP header and the document header and
entity meta data makes sense in both places.
</snip>

In the project to which I am referring, the <system /> element
contains data not currently defined in headers and/or items (sometimes
object graphs) the stakeholders wanted to me sure was "easily
available" to a wide range of clients within the self-descriptive
message. There are a number of items in HTML <head /> that are also
"duplicates" of HTTP headers.

Yes, it's a bit muddled; but it _is_ consistent and well-defined which
was a big win at the time this media-type was designed.

mca
http://amundsen.com/blog/




On Tue, Feb 23, 2010 at 13:32, Jan Algermissen <algermissen1971@...> wrote:
>
> On Feb 23, 2010, at 7:02 PM, mike amundsen wrote:
>
>> Jan:
>>
>> I, too, prefer a large-grained media-type (application level and higher).
>>
>> When you say "...It causes real dispatching pains because you do not
>> know what you have before you poke into the body." �are you referring
>> to dispatch issues on the client? server?
>
> Both, unfortunately. But then - the approach taken cannot rely on certain clients having special, improved features.
>
>>
>> There are a number of factors in designing a media-type. For example,
>> I think over-specifying the document structure can make implementing
>> state-machines against the media-type difficult.
>
> Yes.
>
>>
>> Recently, I've been copying the HTML document structure ((html = head
>> + body) when creating my application-level media types. For example,
>> one large app I'm working on has the following media-type structure:
>>
>
> Yes, that is usually good. However, I also think it is sometimes confusing because you have the HTTP header and the document header and entity meta data makes sense in both places.
>
> jan
>
>> <root>
>> <system /> <!-- system-level meta data and other control values
>> including general links -->
>> <data /> <!-- request-specific data including any lists, item details, etc. -->
>> </root>
>>
>> It's then up to the client and server to understand the details of the
>> <system> and <data> sections such as <user-list /> or <user-details />
>> or <list class="users" /> depending on your approach.
>>
>> mca
>> http://amundsen.com/blog/
>>
>>
>>
>>
>> On Tue, Feb 23, 2010 at 12:40, Jan Algermissen <algermissen1971@...> wrote:
>>> When designing media type(s) for a domain that includes a family of "business document types" (such as Atom does with feed and entry or such as UBL does with catalogue, order, invoice,...) what are the pros and cons of
>>>
>>> 1. Defining one 'big' media type encompassing all documents
>>>
>>> 2. Defining many media types that correspond to the individual "business document types"
>>>
>>>
>>>
>>> Personally, I favor the 'one big media type' ecause I like the type to in a sense identify the domain and to subsum all the processing rules involved. OTH, it causes real dispatching pains because you do not know what you have before you poke into the body.
>>>
>>> I usually address that with the use of a profile parameter in conneg, for example: Accept: application/mydomain;profile=doctypeA[1]. Servers the know the client's preferences and can send the doctypeA (without the need to put the profile parameter on the ContentType header (where it might get stripped my interediaries anyhow).
>>>
>>> However, frameworks seem to be bad at that kind of conneg at the moment, hence this posting :-)
>>>
>>>
>>> Any thoughts or insights?
>>>
>>> Jan
>>>
>>> [1] This works also well with client driven conneg, as in <link href="" rel="" type="application/mydomain;profile=doctypeA"/>
>>>
>>>
>>> ------------------------------------
>>>
>>> Yahoo! Groups Links
>>>
>>>
>>>
>>>
>
> -----------------------------------
> �Jan Algermissen, Consultant
> �NORD Software Consulting
>
> �Mail: algermissen@...
> �Blog: http://www.nordsc.com/blog/
> �Work: http://www.nordsc.com/
> -----------------------------------
>
>
>
>
>

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
 


On 2/23/2010 11:58 AM, Markus KARG wrote:
> this is interesting! As I am working with XSL / XML a lot, I did
> not take such a deep look at JSON. Is that type of link support
> native to JSON or is that just a specific use of JSON?

It is not "native" to application/json, it is part of JSON Schema
(application/schema+json) [1], and is therefore a meta-description of
the links that can understood from the data/documents.

[1] http://tools.ietf.org/html/draft-zyp-json-schema

> I wonder whether the outline type of link description is actually
RESTful:
> I mean, "create order" clearly is a command, and such is not
> document driven but method driven, which in turn looks like RPC to
> me?

"create_order" was just what I used to make it clear, since I thought
you were asking for a way to indicate to a client how to navigate
to/submit a request to create an order (using a POST).

- -- 
Kris Zyp
SitePen
(503) 806-1841
http://sitepen.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
 
iEYEARECAAYFAkuELQsACgkQ9VpNnHc4zAx+/ACgl79LdqrDrkUII9Uz2tSXJkiz
EqcAn0Lx28cSF8A6A5S+il74gAE24ye7
=SW2g
-----END PGP SIGNATURE-----

On Feb 23, 2010, at 7:02 PM, mike amundsen wrote:

> Jan:
> 
> I, too, prefer a large-grained media-type (application level and higher).
> 
> When you say "...It causes real dispatching pains because you do not
> know what you have before you poke into the body."  are you referring
> to dispatch issues on the client? server?

Both, unfortunately. But then - the approach taken cannot rely on certain clients having special, improved features.

> 
> There are a number of factors in designing a media-type. For example,
> I think over-specifying the document structure can make implementing
> state-machines against the media-type difficult.

Yes.

> 
> Recently, I've been copying the HTML document structure ((html = head
> + body) when creating my application-level media types. For example,
> one large app I'm working on has the following media-type structure:
> 

Yes, that is usually good. However, I also think it is sometimes confusing because you have the HTTP header and the document header and entity meta data makes sense in both places.

jan

> <root>
> <system /> <!-- system-level meta data and other control values
> including general links -->
> <data /> <!-- request-specific data including any lists, item details, etc. -->
> </root>
> 
> It's then up to the client and server to understand the details of the
> <system> and <data> sections such as <user-list /> or <user-details />
> or <list class="users" /> depending on your approach.
> 
> mca
> http://amundsen.com/blog/
> 
> 
> 
> 
> On Tue, Feb 23, 2010 at 12:40, Jan Algermissen <algermissen1971@...> wrote:
>> When designing media type(s) for a domain that includes a family of "business document types" (such as Atom does with feed and entry or such as UBL does with catalogue, order, invoice,...) what are the pros and cons of
>> 
>> 1. Defining one 'big' media type encompassing all documents
>> 
>> 2. Defining many media types that correspond to the individual "business document types"
>> 
>> 
>> 
>> Personally, I favor the 'one big media type' ecause I like the type to in a sense identify the domain and to subsum all the processing rules involved. OTH, it causes real dispatching pains because you do not know what you have before you poke into the body.
>> 
>> I usually address that with the use of a profile parameter in conneg, for example: Accept: application/mydomain;profile=doctypeA[1]. Servers the know the client's preferences and can send the doctypeA (without the need to put the profile parameter on the ContentType header (where it might get stripped my interediaries anyhow).
>> 
>> However, frameworks seem to be bad at that kind of conneg at the moment, hence this posting :-)
>> 
>> 
>> Any thoughts or insights?
>> 
>> Jan
>> 
>> [1] This works also well with client driven conneg, as in <link href="" rel="" type="application/mydomain;profile=doctypeA"/>
>> 
>> 
>> ------------------------------------
>> 
>> Yahoo! Groups Links
>> 
>> 
>> 
>> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Can one of you guys/gals explain to me how you determine the media type for each URI returned? This is the one thing that still perplexes me. In your example, you return the name, rel, and URI. But from those three items, how do I set the media type for Content-Type when I want to make a request?

On the server side, I might support different media types for each of my methods, some how I would assume I need to return that info as well so that a developer can set the right media type for the request.

Or perhaps I've completely confused the importance and use of media types with regards to HATEOAS responses that provide potentially multiple links for the activities that can be performed for a given state?

Thank you.



--- On Tue, 2/23/10, Kris Zyp <kris@...> wrote:

From: Kris Zyp <kris@...>
Subject: Re: [rest-discuss] Re: [Jersey] Moved thread to rest-discuss / HATEOAS-via-HTTP: Which HTTP Method to use to follow link?
To: "Markus KARG" <markus@...>
Cc: "'Jan Algermissen'" <algermissen1971@...>, "'REST Discuss'" <rest-discuss@yahoogroups.com>
Date: Tuesday, February 23, 2010, 11:31 AM







 



  


    
      
      
      



-----BEGIN PGP SIGNED MESSAGE----- 

Hash: SHA1 

 





On 2/23/2010 11:58 AM, Markus KARG wrote:

> this is interesting! As I am
working with XSL / XML a lot, I did

> not take such a deep look at JSON. Is that type of link support

> native to JSON or is that just a specific use of JSON?



It is not "native" to application/ json, it is part of JSON Schema

(application/ schema+json) [1], and is therefore a meta-description of

the links that can understood from the data/documents.



[1] http://tools. ietf.org/ html/draft- zyp-json- schema



> I wonder whether the outline
type of link description is actually

RESTful:

> I mean, "create order" clearly
is a command, and such is not

> document driven but method driven, which in turn looks like RPC
to

> me?



"create_order" was just what I used to make it clear, since I thought

you were asking for a way to indicate to a client how to navigate

to/submit a request to create an order (using a POST).



- -- 

Kris Zyp

SitePen

(503) 806-1841

http://sitepen. com

-----BEGIN PGP SIGNATURE--- --


Version: GnuPG v1.4.9 (MingW32)


Comment: Using GnuPG with Mozilla - http://enigmail. mozdev.org/


 

iEYEARECAAYFAkuELQs ACgkQ9VpNnHc4zAx +/ACgl79LdqrDrkU II9Uz2tSXJkiz


EqcAn0Lx28cSF8A6A5S +il74gAE24ye7


=SW2g


-----END PGP SIGNATURE--- --








    
     

    
    


 



  






      

On Sat, Feb 20, 2010 at 6:38 PM, Guilherme Silveira
<guilherme.silveira@...> wrote:
> Hello guys,
>
> Jan Vincent, answering your question about the cache, Restfulie and
> Exylus are the only two clients APIs that I am aware of supporting
> cache (according to the restwiki). You can see how it works here:

If you are using Ruby, Resourceful
(<http://rdoc.info/projects/paul/resourceful>) also has cache support.

Peter

On Tue, Feb 23, 2010 at 9:40 AM, Jan Algermissen
<algermissen1971@...> wrote:

> Personally, I favor the 'one big media type' ecause I like the type to in a sense
> identify the domain and to subsum all the processing rules involved. OTH, it causes
> real dispatching pains because you do not know what you have before you poke
> into the body.

Obviously there's a balance.

But if you're using an encompassing "one big media type", then don't
you inevitably have "large", internal elements with different
semantics?

Contrived example of, say, "financial document" containing "invoice"
and "payment".

Two different, sizable, media types embedded in the generic "financial
document".

So, as a consumer, my "invoice processor" has to basically accept
"any" "financial document" and then check it to see if it actually IS
an invoice. I certainly can't ASSUME it's an invoice, it can be
anything.

But, overall, it doesn't change the semantic load or burden on
consumers trying to leverage the document. The "work" is essentially
the same whether the invoice is embedded in the larger payload, or if
it's its own document. The documentation of the semantics is the same
(largely), the code to leverage that data etc is the same. The large
document doesn't really "gain" anything save a vague promise and a
check to ensure I'm actually working with the right data.

Clearly you don't want ultra fine grained media types (tho, arguably,
that's what a micro format is).

Anyway, that's just the other side of the fence in my opinion of this
discussion.

Regards,

Will Hartung
(willh@...)

<snip>
> So, as a consumer, my "invoice processor" has to basically accept
> "any" "financial document" and then check it to see if it actually IS
> an invoice. I certainly can't ASSUME it's an invoice, it can be
> anything.
</snip>

Yep, this is the trade-off. I've only recently started creating true
state-machine clients, but so far limiting the number of media types
supported by my clients has been less cumbersome than "teaching" my
clients to understand a larger set of variations (invoice, bill of
lading, customer, catalog, etc.) for a single media type.

Time will tell.

mca
http://amundsen.com/blog/




On Tue, Feb 23, 2010 at 21:43, Will Hartung <willh@mirthcorp.com> wrote:
> On Tue, Feb 23, 2010 at 9:40 AM, Jan Algermissen
> <algermissen1971@...> wrote:
>
>> Personally, I favor the 'one big media type' ecause I like the type to in a sense
>> identify the domain and to subsum all the processing rules involved. OTH, it causes
>> real dispatching pains because you do not know what you have before you poke
>> into the body.
>
> Obviously there's a balance.
>
> But if you're using an encompassing "one big media type", then don't
> you inevitably have "large", internal elements with different
> semantics?
>
> Contrived example of, say, "financial document" containing "invoice"
> and "payment".
>
> Two different, sizable, media types embedded in the generic "financial
> document".
>
> So, as a consumer, my "invoice processor" has to basically accept
> "any" "financial document" and then check it to see if it actually IS
> an invoice. I certainly can't ASSUME it's an invoice, it can be
> anything.
>
> But, overall, it doesn't change the semantic load or burden on
> consumers trying to leverage the document. The "work" is essentially
> the same whether the invoice is embedded in the larger payload, or if
> it's its own document. The documentation of the semantics is the same
> (largely), the code to leverage that data etc is the same. The large
> document doesn't really "gain" anything save a vague promise and a
> check to ensure I'm actually working with the right data.
>
> Clearly you don't want ultra fine grained media types (tho, arguably,
> that's what a micro format is).
>
> Anyway, that's just the other side of the fence in my opinion of this
> discussion.
>
> Regards,
>
> Will Hartung
> (willh@...)
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

On Feb 24, 2010, at 3:43 AM, Will Hartung wrote:

> So, as a consumer, my "invoice processor" has to basically accept
> "any" "financial document" and then check it to see if it actually IS
> an invoice. I certainly can't ASSUME it's an invoice, it can be
> anything.

Yes.

That is what the type or profile parameters and conneg should be helping with. If I specifically *ask* for application/finance?type=invoice then I should receive an invoice (but still cannot be sure of course).

Jan


-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

D�rio Abdulrehman wrote:
> 
> I will provide details about the domain I'm working on:
> I have a database with biological data: proteins, genes, regulations,
> etc., and the REST API I would like to design gives access to those
> resources for querying.
>

Interesting.  A REST API may or may not work the same way for each of
those resource types.  I was contacted by another project recently, for
similar purpose, so I'm actually somewhat familiar with part of what
you're trying to do.

>
> Since the types of queries I want to provide are very restricted I
> don't think it fits the OpenSearch model suggested by Craig.
> 

You may be surprised.  The solution I proposed to the other project was
to use Atom as a wrapper for XHTML marked up with RDFa, and OpenSearch
(for the same reasons Craig mentioned), with eXist XMLDB (as they
already used Java, it was an easy choice) as an 'Atom Store' layer in
front of the back-end DBs, with the system actually coded using Xquery.

Doing this exposes subresources at their own URIs by Xpath (without
creating separate DB cells), for example you may have a resource:
/protein/{id} which has subresource:  /protein/{id}//sequence.  Or, you
may have a resource:  /protein/{id}#sequence, we aren't far enough
along to tell whether we're after <sequence> or <div class='sequence'>.

>
> A protein/gene is identified by its name but it has other interesting
> data associated (description, aminoacid sequence, etc.), so I would
> like to model it as a resource that responds to GET, returning a
> media type with that information.
> 

Right.  But, I would bet dollars to donuts that your {id} syntax is
specific to your project, rather than being based on some standard for
naming proteins or genes (those don't translate well into any URI
allocation scheme).  This sort of thing maps directly to atom:id, while
the names of the folks who, say, sequenced a gene maps nicely to atom:
author constructs.  Publication date is atom:published, atom:updated
maps to the date of the most recent research referred to.

I would also be willing to bet that you have some data hierarchies in
there, too.  So, continuing with the "identification of resources"
constraint, you need to figure out those hierarchies before you can
design your URIs -- you won't have /protein or /gene, but rather,
/typeof/protein or /typeof/gene, and other type/subtype relationships.

Do you really want to have a resource, /gene, which can return a list of
every named gene ever discovered in both the Plant and Animal Kingdoms?
Craig referred to this as "filters" in his response.  Human genetics
would be /animal/human/typeof/gene or somesuch.

>
> GET /protein/{id}    =>    Returns media type (JSON for example) with
> description, aminoacid sequence, etc.
> 
> Mutatis mutandis for gene.
> 

Actually, JSON is about the worst choice you can make for this sort of
project.  It's too general a media type, doesn't define links, is not
extensible, has no semantics, can't be validated against a schema, and
anything you return as JSON is completely inaccessible to boot.  Your
system is really a searchable collection of documents.  JSON isn't a
document markup language, so it's out-of-place for your purposes.

What's called for is a structured markup language.  The data your
service returns will be organized into lists and tables.  JSON has no
semantics for expressing tabular or listed data.  XHTML does, with the
benefit that XHTML tables and lists may be marked up for accessibility.

The fact is that an XHTML data table is human- and machine- readable,
accessibly -- and that no such capability exists in JSON.  So instead
of reinventing common hypertext data structures like lists and tables
in JSON, focus your efforts on defining a domain-specific vocabulary
for these data structures, expressed inside a standard (X)HTML media
type.

This promotes serendipitous re-use.  You could also come up with your
own XML language, but as with JSON you'd have to reinvent several
wheels to make that work.  Whereas XHTML tables make the generic
"tabular data" structure self-evident.  Embedding metadata in (X)HTML
using RDFa is standard, so no special parser is required to read it,
and it would be simple to re-use across projects.

The easier you make it, the more likely it will be adopted by others.
Using RDFa to add semantics to XHTML tables is simple, and easily
understood. Not so for metadata in JSON, where I have to refer to some
sort of external documentation just to decipher your data structures,
before I can begin to figure out what your vocabulary is.

Instead, you should be relying on my common knowledge of hypertext data
structures, to impart "tabular data" to me through your API.  Since I
already understand hypertext tables, your specific vocabulary sticks
out, and is thus easy for me to understand, since you're establishing
your definitions as an extension of my working knowledge of their
underlying data structure.

As opposed to making me start from scratch, requiring me to learn your
interpretation of tabular data expressed as JSON before I can recognize
your domain-specific vocabulary embedded within.  I use tables as an
example, but I mean any data structure that can be implemented within
the basic semantics of HTML.

If the other project took my advice, which I don't think they did, then
there may already exist an RDFa ontology that partly covers what you're
doing, and you'd just be extending that.  There is nothing inherent to
your resources that would require nonstandard media types to express.

Publishing scientific data on the Web is exactly the problem HTML was
originally conceived to solve.  It did spectacularly well.  Use it.

Constrain it to your ontology using RELAX NG and Schematron.  Nowadays,
wrap it in Atom.  If you need a new element, like say <sequence>, both
XHTML and Atom are extensible to allow for it.  PCR imaging is saved as
what, PNG files?  Make Atom Media Entries for them, properly linked all
around.

If you're generating images from DB queries, save the image as a file
with a name and link to that, instead of generating the same image from
the DB with every request by calling some image-generation endpoint.
Don't expose the image-generating endpoint to the public, it's a DDoS
magnet.  Every online genetic DB I've looked at, clearly uses image
generation, which is obvious by looking at the URLs.  It shouldn't be.

> 
> Given the above description of the resources does it still make sense
> to provide the batch version of the resource?
> I see the users wanting to GET information about a list of
> proteins/genes and it would certainly be useful to do it batch style.
> 

If you follow my advice, you'd have an eXist XMLDB and a whole bunch of
stored procedures (resources).  Then you could simply turn on Atom
Protocol.  A researcher could log in, create a workspace, populate it
with some search results, write some custom Xquery code to create their
own search results, then query against their own contrived collection
of, essentially, stored procedures.

This, to me, is the most important aspect of my solution.  There's no
way of telling how someone may want to access your data -- ways that
haven't occurred to you.  By virtue of publishing your data in an XMLDB
that allows direct Xquery access, you avoid this problem (by basically
making the number of "resources" in your system infinite).

If someone doesn't like your REST API, they could just write their own.
Those without login privileges to the XMLDB are stuck using the REST
API you provide for them, restricted to using your system only in ways
you have specifically anticipated they'll need.

I don't see an overwhelming need, in light of this, to provide some way
to submit multiple searches in one request.  Even if you could make it
work in browsers.  I suppose it could be done even if _I_ don't see why,
and it could probably be made RESTful, but there would be a cost in
reduced visibility.

While that isn't a REST constraint, it's my process to weigh the pros
and cons.  The con of reduced visibility is a stopper for me, unless
I'm gaining the benefit of some pro in return.  I don't see the pro
here, so I don't see any benefit to reducing visibility to support a
batch-GET feature.

>
> > >
> > > 2.
> > > I have another resource which is an algorithm that takes as input:
> > > - a list of parameters [x1, x2, ...]
> > > - another list of parameters [y1, y2, ...]
> > > - some other optional arguments
> > >
> >
> > Let's try to model that resource, first of all, by calling it a
> > service endpoint.  Then we can get down to the brass tacks of
> > implementation.
> >
> 
> This resource is an algorithm that takes as input lists of proteins,
> genes and some other parameters and outputs the results.
> 

OK, *that* sounds like an RPC endpoint.  You don't want an endpoint
that takes some query syntax, you just want some query syntax.  I'll
elaborate on this later, I have some example URIs I can adapt from that
other project (I've already solved this problem for someone else, so I
can skip a few steps here and start throwing hypothetical URIs around).

> 
> Given the nature of the resources I hope it should now be easier to
> design a URI scheme.
> 

Nope, not yet.  The URI allocation scheme will consist of hierarchical
resources and a query syntax.  We haven't identified the hierarchy, or
worked out the query syntax, yet.  That's assuming you even agree to
using Atom, which I usually recommend for the purpose of prototyping,
even when I don't know it's a good fit.

In this case, I'm pretty sure it's a good fit, and I have an idea of
where to separate client logic from server logic.  The only thing I can
say about URI design, is that the query syntax might go in a query, or
it might go in a fragment, or it might wind up in both.  IOW, nothing's
settled.

-Eric

On Wed, Feb 24, 2010 at 1:49 AM, Jan Algermissen
<algermissen1971@...> wrote:

> That is what the type or profile parameters and conneg should be
> helping with. If I specifically *ask* for
> application/finance?type=invoice then I should receive an invoice
> (but still cannot be sure of course).

How is 'application/finance?type=invoice' different than
'application/invoice'?

Using a parameter on the mime type has the practical disadvantage very
few, if any, exiting tools handle conneg using media type parameters
smartly.  With a discreet media type you have a fighting chance of
finding a tool that will support conneg.

To your original question, i prefer to construct media types that are
the larger than a single document type.  Media types should be
cohesive, though.  To use some of the examples from earlier in the
thread, a media type including invoice and payment document types
seems pretty reasonable but i would probably put a catalog document
type in a different media type.

Peter
http://barelyenough.org

Jan,

Have you tried to communicate with the UBL gang to see if they are
interested in defining media types?

That would be the best route:  getting some semi-popular semi-standard
organization to define some standard media types for business.

Then, whatever variation they define would probably be better for REST
than whatever you and I define, regardless of much I might prefer my
own format.

What I wonder about is whether we actually need a definition of the methods:
If we would "normalize" all RESTful documents down to atomic CRUD
operations, then it would be clear what GET / PUT / POST / DELETE are to be
used for. I mean, we all can use any database table just by SELECT / UPDATE
/ INSERT / DELETE without any documentation about what the actual use the
command is, and we can normalize a database to hold any type of business
data. So why do we need to agree upon documents types and link rels at all?
Why don't we just normalize our apps?

 

From: Kris Zyp [mailto:kris@...] 
Sent: Dienstag, 23. Februar 2010 20:31
To: Markus KARG
Cc: 'Jan Algermissen'; 'REST Discuss'
Subject: Re: [rest-discuss] Re: [Jersey] Moved thread to rest-discuss /
HATEOAS-via-HTTP: Which HTTP Method to use to follow link?

 

-----BEGIN PGP SIGNED MESSAGE----- 
Hash: SHA1 
 


On 2/23/2010 11:58 AM, Markus KARG wrote:
> this is interesting! As I am

working with XSL / XML a lot, I did



> not take such a deep look at JSON. Is that type of link support



> native to JSON or is that just a specific use of JSON?

It is not "native" to application/json, it is part of JSON Schema
(application/schema+json) [1], and is therefore a meta-description of
the links that can understood from the data/documents.

[1] http://tools.ietf.org/html/draft-zyp-json-schema

> I wonder whether the outline

type of link description is actually
RESTful:
> I mean, "create order" clearly

is a command, and such is not



> document driven but method driven, which in turn looks like RPC

to



> me?

"create_order" was just what I used to make it clear, since I thought
you were asking for a way to indicate to a client how to navigate
to/submit a request to create an order (using a POST).

- -- 
Kris Zyp
SitePen
(503) 806-1841
http://sitepen.com
-----BEGIN PGP SIGNATURE----- 
Version: GnuPG v1.4.9 (MingW32) 
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ 
 
iEYEARECAAYFAkuELQsACgkQ9VpNnHc4zAx+/ACgl79LdqrDrkUII9Uz2tSXJkiz 
EqcAn0Lx28cSF8A6A5S+il74gAE24ye7 
=SW2g 
-----END PGP SIGNATURE----- 

If we stick to http in the original definition's sense, you don't need to define the mime type at all: The client will supply a list of accepted media type preferences in a request, and will get one of those back. The actual returned type is found in the header. If you want ONLY the header, don't use GET but HEAD. Rather simple, isn't it?

 

From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com] On Behalf Of Kevin Duffey
Sent: Dienstag, 23. Februar 2010 21:34
To: rest-discuss@yahoogroups.com
Subject: Re: [rest-discuss] Re: [Jersey] Moved thread to rest-discuss / HATEOAS-via-HTTP: Which HTTP Method to use to follow link?

 







Can one of you guys/gals explain to me how you determine the media type for each URI returned? This is the one thing that still perplexes me. In your example, you return the name, rel, and URI. But from those three items, how do I set the media type for Content-Type when I want to make a request?

On the server side, I might support different media types for each of my methods, some how I would assume I need to return that info as well so that a developer can set the right media type for the request.

Or perhaps I've completely confused the importance and use of media types with regards to HATEOAS responses that provide potentially multiple links for the activities that can be performed for a given state?

Thank you.



--- On Tue, 2/23/10, Kris Zyp <kris@sitepen.com> wrote:


From: Kris Zyp <kris@...>
Subject: Re: [rest-discuss] Re: [Jersey] Moved thread to rest-discuss / HATEOAS-via-HTTP: Which HTTP Method to use to follow link?
To: "Markus KARG" <markus@headcrashing.eu>
Cc: "'Jan Algermissen'" <algermissen1971@...>, "'REST Discuss'" <rest-discuss@yahoogroups.com>
Date: Tuesday, February 23, 2010, 11:31 AM

  

-----BEGIN PGP SIGNED MESSAGE----- 
Hash: SHA1 
 


On 2/23/2010 11:58 AM, Markus KARG wrote:
> this is interesting! As I am
working with XSL / XML a lot, I did

> not take such a deep look at JSON. Is that type of link support

> native to JSON or is that just a specific use of JSON?

It is not "native" to application/ json, it is part of JSON Schema
(application/ schema+json) [1], and is therefore a meta-description of
the links that can understood from the data/documents.

[1] http://tools. <http://tools.ietf.org/html/draft-zyp-json-schema>  ietf.org/ html/draft- zyp-json- schema

> I wonder whether the outline
type of link description is actually
RESTful:
> I mean, "create order" clearly
is a command, and such is not

> document driven but method driven, which in turn looks like RPC
to

> me?

"create_order" was just what I used to make it clear, since I thought
you were asking for a way to indicate to a client how to navigate
to/submit a request to create an order (using a POST).

- -- 
Kris Zyp
SitePen
(503) 806-1841
http://sitepen. com <http://sitepen.com> 
-----BEGIN PGP SIGNATURE--- -- 
Version: GnuPG v1.4.9 (MingW32) 
Comment: Using GnuPG with Mozilla - http://enigmail. mozdev.org/ <http://enigmail.mozdev.org/>  
 
iEYEARECAAYFAkuELQs ACgkQ9VpNnHc4zAx +/ACgl79LdqrDrkU II9Uz2tSXJkiz 
EqcAn0Lx28cSF8A6A5S +il74gAE24ye7 
=SW2g 
-----END PGP SIGNATURE--- -- 

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
 
I think that forcing REST to strictly conform to CRUD is considered a
REST anti-pattern. Applications can have actions outside of pure CRUD
actions, and servers should be allowed to provide navigation to
non-safe, non-idempotent resource-oriented actions through POSTs (like
a form that triggers the sending of an email from the server, for
example).
Kris

On 2/24/2010 11:16 AM, Markus KARG wrote:
>
> What I wonder about is whether we actually need a definition of the
> methods: If we would "normalize" all RESTful documents down to
> atomic CRUD operations, then it would be clear what GET / PUT /
> POST / DELETE are to be used for. I mean, we all can use any
> database table just by SELECT / UPDATE / INSERT / DELETE without
> any documentation about what the actual use the command is, and we
> can normalize a database to hold any type of business data. So why
> do we need to agree upon documents types and link rels at all? Why
> don't we just normalize our apps?
>
>
>
> *From:* Kris Zyp [mailto:kris@...] *Sent:* Dienstag, 23.
> Februar 2010 20:31 *To:* Markus KARG *Cc:* 'Jan Algermissen'; 'REST
> Discuss' *Subject:* Re: [rest-discuss] Re: [Jersey] Moved thread to
> rest-discuss / HATEOAS-via-HTTP: Which HTTP Method to use to follow
> link?
>
>
>
>
>
> On 2/23/2010 11:58 AM, Markus KARG wrote:
>> this is interesting! As I am
>
> working with XSL / XML a lot, I did
>
>> not take such a deep look at JSON. Is that type of link support
>
>> native to JSON or is that just a specific use of JSON?
>
> It is not "native" to application/json, it is part of JSON Schema
> (application/schema+json) [1], and is therefore a meta-description
> of the links that can understood from the data/documents.
>
> [1] http://tools.ietf.org/html/draft-zyp-json-schema
>
>> I wonder whether the outline
>
> type of link description is actually RESTful:
>> I mean, "create order" clearly
>
> is a command, and such is not
>
>> document driven but method driven, which in turn looks like RPC
>
> to
>
>> me?
>
> "create_order" was just what I used to make it clear, since I
> thought you were asking for a way to indicate to a client how to
> navigate to/submit a request to create an order (using a POST).
>

- -- 
Kris Zyp
SitePen
(503) 806-1841
http://sitepen.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
 
iEYEARECAAYFAkuFceoACgkQ9VpNnHc4zAxJCgCghuhhnEinnB8yfrhU5VlexchS
dpgAnjUgssc0Y8zO29HXHEKwhSsDBPcl
=XHCs
-----END PGP SIGNATURE-----

I think we must differentiate here between CRUD GUIs (which I dislike) and
CRUD APIs: As SQL works so well, I don't actually see a real need to invent
more commands. I mean, what benefit should it actually bringt? If I want my
server to send an email, what would be wrong to say that I must do a POST to
the "http://.../mail-outbox/" URI, which in turn will make the server send
away the received entity as an email, and which ist a RESTful operation
(nobody says that CRUD means that a resource must be persistent *forever*,
so the server is free to DELETE it on it's own once the mail is sent). I
just don't see a need to do anything besides CRUD, but maybe I just didn't
find the ultimate example?

 

From: Kris Zyp [mailto:kris@...] 
Sent: Mittwoch, 24. Februar 2010 19:38
To: Markus KARG
Cc: 'Jan Algermissen'; 'REST Discuss'
Subject: Re: [rest-discuss] Re: [Jersey] Moved thread to rest-discuss /
HATEOAS-via-HTTP: Which HTTP Method to use to follow link?

 

-----BEGIN PGP SIGNED MESSAGE----- 
Hash: SHA1 
 
I think that forcing REST to strictly conform to CRUD is considered a
REST anti-pattern. Applications can have actions outside of pure CRUD
actions, and servers should be allowed to provide navigation to
non-safe, non-idempotent resource-oriented actions through POSTs (like
a form that triggers the sending of an email from the server, for
example).
Kris

On 2/24/2010 11:16 AM, Markus KARG wrote:
> 



> What I wonder about is whether we actually need a definition of

the



> methods: If we would "normalize" all RESTful documents down to



> atomic CRUD operations, then it would be clear what GET / PUT /



> POST / DELETE are to be used for. I mean, we all can use any



> database table just by SELECT / UPDATE / INSERT / DELETE without



> any documentation about what the actual use the command is, and

we



> can normalize a database to hold any type of business data. So

why



> do we need to agree upon documents types and link rels at all?

Why



> don't we just normalize our apps?



> 



> 



> 



> *From:* Kris Zyp [mailto:kris@...] *Sent:* Dienstag, 23.



> Februar 2010 20:31 *To:* Markus KARG *Cc:* 'Jan Algermissen';

'REST



> Discuss' *Subject:* Re: [rest-discuss] Re: [Jersey] Moved thread

to



> rest-discuss / HATEOAS-via-HTTP: Which HTTP Method to use to

follow



> link?



> 



> 



> 



> 



> 



> On 2/23/2010 11:58 AM, Markus KARG wrote:



>> this is interesting! As I am



> 



> working with XSL / XML a lot, I did



> 



>> not take such a deep look at JSON. Is that type of link

support



> 



>> native to JSON or is that just a specific use of JSON?



> 



> It is not "native" to application/json, it is part of JSON

Schema 



> (application/schema+json) [1], and is therefore a

meta-description



> of the links that can understood from the data/documents.



> 



> [1] http://tools.ietf.org/html/draft-zyp-json-schema



> 



>> I wonder whether the outline



> 



> type of link description is actually RESTful:



>> I mean, "create order" clearly



> 



> is a command, and such is not



> 



>> document driven but method driven, which in turn looks like

RPC



> 



> to



> 



>> me?



> 



> "create_order" was just what I used to make it clear, since I



> thought you were asking for a way to indicate to a client how to



> navigate to/submit a request to create an order (using a POST).



> 

- -- 
Kris Zyp
SitePen
(503) 806-1841
http://sitepen.com
-----BEGIN PGP SIGNATURE----- 
Version: GnuPG v1.4.9 (MingW32) 
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ 
 
iEYEARECAAYFAkuFceoACgkQ9VpNnHc4zAxJCgCghuhhnEinnB8yfrhU5VlexchS 
dpgAnjUgssc0Y8zO29HXHEKwhSsDBPcl 
=XHCs 
-----END PGP SIGNATURE----- 

Ho Bob,

On Feb 24, 2010, at 5:11 PM, Bob Haugen wrote:

> Jan,
> 
> Have you tried to communicate with the UBL gang to see if they are
> interested in defining media types?
> 

Yes, I asked a while ago (can't find the link right now). They were not really interested because they said UBL was intended as message payload (paraphrasing) and should not contain 'processing intention'. I'll try to find the answer later.

Have you seen my 'SCM quest'? See http://www.nordsc.com/blog/?cat=13

The media type is discussed here: http://www.nordsc.com/blog/?p=293

I take an experimental shot at a UBL media type - but really only to show how it could be done.


> That would be the best route:  getting some semi-popular semi-standard
> organization to define some standard media types for business.

Yes - Web UBL.... WUBL :-)

> 
> Then, whatever variation they define would probably be better for REST
> than whatever you and I define, regardless of much I might prefer my
> own format.

Yes, they certainly know the nuts and bolts - which is probably why UBL enables almost anything :-) However, stripping it down works quite nicely and it is understandable then.

Thanks,

Jan

> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Markus,

What I meant was... what does the response look like? Is it something like:

<links>
�� <link rel="create" uri="...." method="post" media-type="application/xml, application/json"/>
� <link rel="self" uir="..." method="get, put" media-type="application/xml"/>
</links>

That is.. if I do some sort of GET or OPTION or what have you on a published URI, and two URIs come back indicating I can get the self and post a create to another URI, given that we can specify different media types on each method (at least in Jersey), I am curious what lets the client side no WHAT to set the header Content-Type to, in order to get it to the right method on the server side for handling?

With JAX-RS, we can specify two methods from above:

@POST
@Consumes({"application/xml", "application/json"})
public Response create(...){}

@PUT
@Consumes({"application/xml"})
public Response update(...){}

@GET
@Produces({"application/xml"})
public Response get(...){}


I am curious as I try to build out a HATEOAS based response system, how I send back multiple links that can be called by the client at that point, and how I tell the client the specific media type each URI can handle? Or is that in a document instead that says "for this URI, you must use the media type..."?



--- On Wed, 2/24/10, Markus KARG <markus@...> wrote:

From: Markus KARG <markus@...>
Subject: RE: [rest-discuss] Re: [Jersey] Moved thread to rest-discuss / HATEOAS-via-HTTP: Which HTTP Method to use to follow link?
To: "'Kevin Duffey'" <andjarnic@...>, rest-discuss@yahoogroups.com
Date: Wednesday, February 24, 2010, 10:19 AM




 
 







If we stick to http in the original definition's sense, you
don't need to define the mime type at all: The client will supply a list of
accepted media type preferences in a request, and will get one of those back.
The actual returned type is found in the header. If you want ONLY the header,
don't use GET but HEAD. Rather simple, isn't it? 

 � 







From: rest-discuss@yahoogroups.com
[mailto:rest-discuss@yahoogroups.com] On Behalf Of Kevin Duffey

Sent: Dienstag, 23. Februar 2010 21:34

To: rest-discuss@yahoogroups.com

Subject: Re: [rest-discuss] Re: [Jersey] Moved thread to rest-discuss /
HATEOAS-via-HTTP: Which HTTP Method to use to follow link? 





 � 







 


 
  
  Can one of you guys/gals explain to me how you determine
  the media type for each URI returned? This is the one thing that still
  perplexes me. In your example, you return the name, rel, and URI. But from
  those three items, how do I set the media type for Content-Type when I want
  to make a request?

  

  On the server side, I might support different media types for each of my
  methods, some how I would assume I need to return that info as well so that a
  developer can set the right media type for the request.

  

  Or perhaps I've completely confused the importance and use of media types
  with regards to HATEOAS responses that provide potentially multiple links for
  the activities that can be performed for a given state?

  

  Thank you.

  

  

  

  --- On Tue, 2/23/10, Kris Zyp <kris@...> wrote: 
  

  From: Kris Zyp <kris@sitepen.com>

  Subject: Re: [rest-discuss] Re: [Jersey] Moved thread to rest-discuss /
  HATEOAS-via-HTTP: Which HTTP Method to use to follow link?

  To: "Markus KARG" <markus@...>

  Cc: "'Jan Algermissen'" <algermissen1971@...>,
  "'REST Discuss'" <rest-discuss@yahoogroups.com>

  Date: Tuesday, February 23, 2010, 11:31 AM 
  
  �  
  
  -----BEGIN PGP SIGNED MESSAGE----- 

  Hash: SHA1 

  �

  

  

  On 2/23/2010 11:58 AM, Markus KARG wrote:

  > this is interesting! As I am

  working with XSL / XML a lot, I did

  

  > not take such a deep look at JSON. Is that type of link support

  

  > native to JSON or is that just a specific use of JSON?

  

  It is not "native" to application/ json, it is part of JSON Schema

  (application/ schema+json) [1], and is therefore a meta-description of

  the links that can understood from the data/documents.

  

  [1] http://tools.
  ietf.org/ html/draft- zyp-json- schema

  

  > I wonder whether the outline

  type of link description is actually

  RESTful:

  > I mean, "create order" clearly

  is a command, and such is not

  

  > document driven but method driven, which in turn looks like RPC

  to

  

  > me?

  

  "create_order" was just what I used to make it clear, since I thought

  you were asking for a way to indicate to a client how to navigate

  to/submit a request to create an order (using a POST).

  

  - -- 

  Kris Zyp

  SitePen

  (503) 806-1841

  http://sitepen. com

  -----BEGIN PGP SIGNATURE--- -- 

  Version: GnuPG v1.4.9 (MingW32) 

  Comment: Using GnuPG with Mozilla - http://enigmail. mozdev.org/ 

  �

  iEYEARECAAYFAkuELQs ACgkQ9VpNnHc4zAx +/ACgl79LdqrDrkU II9Uz2tSXJkiz 

  EqcAn0Lx28cSF8A6A5S +il74gAE24ye7 

  =SW2g 

  -----END PGP SIGNATURE--- --  
  
  
  
 










 



 







 




      

On Wed, Feb 24, 2010 at 2:28 PM, Jan Algermissen
<algermissen1971@...> wrote:
> On Feb 24, 2010, at 5:11 PM, Bob Haugen wrote:
>> Have you tried to communicate with the UBL gang to see if they are
>> interested in defining media types?
>>
>
> Yes, I asked a while ago (can't find the link right now). They were not really interested because they said UBL was intended as message payload (paraphrasing) and should not contain 'processing intention'. I'll try to find the answer later.
>

So how does media type contain processing intention?  (Unless they
mean "web" vs "SOAP"? I think they started assuming either typical EDI
transport mechanisms or SOAP.)

>> That would be the best route: �getting some semi-popular semi-standard
>> organization to define some standard media types for business.
>
> Yes - Web UBL.... WUBL :-)
>
>>
>> Then, whatever variation they define would probably be better for REST
>> than whatever you and I define, regardless of much I might prefer my
>> own format.
>
> Yes, they certainly know the nuts and bolts - which is probably why UBL enables almost anything :-) However, stripping it down works quite nicely and it is understandable then.
>

Enabling almost anything is the curse of EDI standards (of which UBL
is a bastard child), which makes them fiendishly complex to work with.
 Back in the day, companies used to define subsets.

On Feb 24, 2010, at 10:56 PM, Bob Haugen wrote:

> On Wed, Feb 24, 2010 at 2:28 PM, Jan Algermissen
> <algermissen1971@...> wrote:
>> On Feb 24, 2010, at 5:11 PM, Bob Haugen wrote:
>>> Have you tried to communicate with the UBL gang to see if they are
>>> interested in defining media types?
>>> 
>> 
>> Yes, I asked a while ago (can't find the link right now). They were not really interested because they said UBL was intended as message payload (paraphrasing) and should not contain 'processing intention'. I'll try to find the answer later.

Here is the thread: <http://lists.oasis-open.org/archives/ubl-dev/200802/msg00050.html>

(Re media type: see at bottom and read response ref-ed below)



>> 
> 
> So how does media type contain processing intention?  (Unless they
> mean "web" vs "SOAP"? I think they started assuming either typical EDI
> transport mechanisms or SOAP.)

This is the answer mail <http://lists.oasis-open.org/archives/ubl-dev/200802/msg00052.html>


> 
>>> That would be the best route:  getting some semi-popular semi-standard
>>> organization to define some standard media types for business.
>> 
>> Yes - Web UBL.... WUBL :-)
>> 
>>> 
>>> Then, whatever variation they define would probably be better for REST
>>> than whatever you and I define, regardless of much I might prefer my
>>> own format.
>> 
>> Yes, they certainly know the nuts and bolts - which is probably why UBL enables almost anything :-) However, stripping it down works quite nicely and it is understandable then.
>> 
> 
> Enabling almost anything is the curse of EDI standards (of which UBL
> is a bastard child), which makes them fiendishly complex to work with.
> Back in the day, companies used to define subsets.

The question would be I guess if a common 80/20[1] subset could be defined or if it is the nature of EDI that the parties must define an agreed subtype by themselves.

[1] IIRC UBL is already aimed to be an 80/20 EDI :-)

Jan


-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

On Wed, Feb 24, 2010 at 4:09 PM, Jan Algermissen
<algermissen1971@...> wrote:
> On Feb 24, 2010, at 10:56 PM, Bob Haugen wrote:
>> So how does media type contain processing intention? �(Unless they
>> mean "web" vs "SOAP"? I think they started assuming either typical EDI
>> transport mechanisms or SOAP.)
>
> This is the answer mail <http://lists.oasis-open.org/archives/ubl-dev/200802/msg00052.html>

I would not read that answer, and especially the followup, the way you
did in your summary.  The responders do not seem to have thought of
the issue very deeply, but appear to be to be sympathetic.  They
appear to have assumed a message-passing architecture (that is, they
do assume a processing intention in that sense), not a REST or
resource-oriented architecture.

I also got the idea that if somebody knew how to define a UBL media
type or two, they might like it.

Where did you get "They were not really interested because they said
UBL was intended as message payload (paraphrasing) and should not
contain 'processing intention'"?

On Feb 24, 2010, at 11:47 PM, Bob Haugen wrote:

> On Wed, Feb 24, 2010 at 4:09 PM, Jan Algermissen
> <algermissen1971@...> wrote:
>> On Feb 24, 2010, at 10:56 PM, Bob Haugen wrote:
>>> So how does media type contain processing intention?  (Unless they
>>> mean "web" vs "SOAP"? I think they started assuming either typical EDI
>>> transport mechanisms or SOAP.)
>> 
>> This is the answer mail <http://lists.oasis-open.org/archives/ubl-dev/200802/msg00052.html>
> 
> I would not read that answer, and especially the followup, the way you
> did in your summary.  The responders do not seem to have thought of
> the issue very deeply, but appear to be to be sympathetic.  They
> appear to have assumed a message-passing architecture (that is, they
> do assume a processing intention in that sense), not a REST or
> resource-oriented architecture.

Well, yes :-) What I wanted back then was to see if there was interest in the UBL community to bring UBL 'on the Web'. I did not have a 'mission' to actually do that.

> 
> I also got the idea that if somebody knew how to define a UBL media
> type or two, they might like it.

Maybe - OTH, I understood from the response that UBL is not meant to be used without an acompanying agreement tailored towards the communicating partners. I think the position is that UBL itself is not contracturally binding enough to work without such side agreements. But of course I might have completely misunderstood that.


> 
> Where did you get "They were not really interested because they said
> UBL was intended as message payload (paraphrasing) and should not
> contain 'processing intention'"?

It was the memory of the mail before I had found it in the archive. Not very precise :-)

Are you interested in persuing a UBL (procurement) media type? I lack the knowledge of the real world supply chain to judge whether a general format is suitable for a reasonable percentage of actual requirements.

Jan



> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

On Wed, Feb 24, 2010 at 10:50 AM, Markus KARG <markus@...> wrote:
>
>
>
> I think we must differentiate here between CRUD GUIs (which I dislike) and CRUD APIs:
> As SQL works so well, I don't actually see a real need to invent more commands. I mean,
> what benefit should it actually bringt?

You gain a API that has better granularity than simply CRUD. Yes,
inevitably, you end up doing pure "atomic" CRUD against, say, a SQL
database. But there's no reason you should be forced to exposed that
limited of an API to your clients. You should be able to have higher
level interactions with your sever than just raw CRUD, actions that
themselves may manifest into sever primitive hits against your data
store.

The point of the Common Interface isn't so much to hamstring
applications in to a pure CRUD HTTP view of the world, but rather to
help ensure you don't simply run off hog wild creating eleventy
zillion new verbs. Taking a constrained, conservative view at the verb
layer and how they're used can make the API easier to use, and more
approachable, rather than a wiener dog nest of exceptions and special
cases and what ifs. Consistent application of a consistent, common
interface.

But that doesn't mean you're limited solely to CRUD.

Regards,

Will Hartung
(willh@...)

On Feb 24, 2010, at 7:50 PM, Markus KARG wrote:

> 
> 
> I think we must differentiate here between CRUD GUIs (which I dislike) and CRUD APIs: As SQL works so well, I don't actually see a real need to invent more commands. I mean, what benefit should it actually bringt? If I want my server to send an email, what would be wrong to say that I must do a POST to the "http://.../mail-outbox/" URI, which in turn will make the server send away the received entity as an email, and which ist a RESTful operation

Nothing is wrong with that. That is how domain specific operations ('goals' if you want) are achieved: tell a resource *with the appropriate semantics* to process-this (POST). So, if you learned from some hypermedia that http://.../mail-outbox/ has the semantics of sending a mail when you POST something to it then that is how you achieve that domain goal.

The need for the hypermedia is there because that is how the client learns ar runtime that http://.../mail-outbox/ has these semantics.

Note: if the general semantics of the domain operation map to PUT or DELETE or PATCH these specific methods should be used because you get more visibility compared to POST (which has visibility zero). For example, a PUT on /orders/2 allows caches to flush what they have for /orders/2 and store the response to the PUT. If you POST /orders/2 the caches just flush - and they only do this not because they know what is going on but because that is the (necessary) default behavior for POST.

Jan



> (nobody says that CRUD means that a resource must be persistent *forever*, so the server is free to DELETE it on it's own once the mail is sent). I just don't see a need to do anything besides CRUD, but maybe I just didn't find the ultimate example?
>  
> From: Kris Zyp [mailto:kris@...] 
> Sent: Mittwoch, 24. Februar 2010 19:38
> To: Markus KARG
> Cc: 'Jan Algermissen'; 'REST Discuss'
> Subject: Re: [rest-discuss] Re: [Jersey] Moved thread to rest-discuss / HATEOAS-via-HTTP: Which HTTP Method to use to follow link?
>  
> -----BEGIN PGP SIGNED MESSAGE----- 
> Hash: SHA1 
>  
> I think that forcing REST to strictly conform to CRUD is considered a
> REST anti-pattern. Applications can have actions outside of pure CRUD
> actions, and servers should be allowed to provide navigation to
> non-safe, non-idempotent resource-oriented actions through POSTs (like
> a form that triggers the sending of an email from the server, for
> example).
> Kris
> 
> On 2/24/2010 11:16 AM, Markus KARG wrote:
> > 
> 
> > What I wonder about is whether we actually need a definition of
> the
> 
> > methods: If we would "normalize" all RESTful documents down to
> 
> > atomic CRUD operations, then it would be clear what GET / PUT /
> 
> > POST / DELETE are to be used for. I mean, we all can use any
> 
> > database table just by SELECT / UPDATE / INSERT / DELETE without
> 
> > any documentation about what the actual use the command is, and
> we
> 
> > can normalize a database to hold any type of business data. So
> why
> 
> > do we need to agree upon documents types and link rels at all?
> Why
> 
> > don't we just normalize our apps?
> 
> > 
> 
> > 
> 
> > 
> 
> > *From:* Kris Zyp [mailto:kris@...] *Sent:* Dienstag, 23.
> 
> > Februar 2010 20:31 *To:* Markus KARG *Cc:* 'Jan Algermissen';
> 'REST
> 
> > Discuss' *Subject:* Re: [rest-discuss] Re: [Jersey] Moved thread
> to
> 
> > rest-discuss / HATEOAS-via-HTTP: Which HTTP Method to use to
> follow
> 
> > link?
> 
> > 
> 
> > 
> 
> > 
> 
> > 
> 
> > 
> 
> > On 2/23/2010 11:58 AM, Markus KARG wrote:
> 
> >> this is interesting! As I am
> 
> > 
> 
> > working with XSL / XML a lot, I did
> 
> > 
> 
> >> not take such a deep look at JSON. Is that type of link
> support
> 
> > 
> 
> >> native to JSON or is that just a specific use of JSON?
> 
> > 
> 
> > It is not "native" to application/json, it is part of JSON
> Schema 
> 
> > (application/schema+json) [1], and is therefore a
> meta-description
> 
> > of the links that can understood from the data/documents.
> 
> > 
> 
> > [1] http://tools.ietf.org/html/draft-zyp-json-schema
> 
> > 
> 
> >> I wonder whether the outline
> 
> > 
> 
> > type of link description is actually RESTful:
> 
> >> I mean, "create order" clearly
> 
> > 
> 
> > is a command, and such is not
> 
> > 
> 
> >> document driven but method driven, which in turn looks like
> RPC
> 
> > 
> 
> > to
> 
> > 
> 
> >> me?
> 
> > 
> 
> > "create_order" was just what I used to make it clear, since I
> 
> > thought you were asking for a way to indicate to a client how to
> 
> > navigate to/submit a request to create an order (using a POST).
> 
> > 
> 
> - -- 
> Kris Zyp
> SitePen
> (503) 806-1841
> http://sitepen.com
> -----BEGIN PGP SIGNATURE----- 
> Version: GnuPG v1.4.9 (MingW32) 
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ 
>  
> iEYEARECAAYFAkuFceoACgkQ9VpNnHc4zAxJCgCghuhhnEinnB8yfrhU5VlexchS 
> dpgAnjUgssc0Y8zO29HXHEKwhSsDBPcl 
> =XHCs 
> -----END PGP SIGNATURE-----
> 
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Hi,

I have put together a table classifying HTTP-based API-types according to the REST constraints they adhere to:

<http://nordsc.com/ext/classification_of_http_based_apis.html>

Hope this is useful.

Jan

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

On Wed, Feb 24, 2010 at 1:31 PM, Jan Algermissen
<algermissen1971@...> wrote:

>> To your original question, i prefer to construct media types that are
>> the larger than a single document type. �Media types should be
>> cohesive, though. �To use some of the examples from earlier in the
>> thread, a media type including invoice and payment document types
>> seems pretty reasonable but i would probably put a catalog document
>> type in a different media type.
>
> I pout catalog in because it is a common doc type from the procurement domain. I wonder: why would you put it into a separate type?

It is purely a matter of taste.  Basically, i don't see much cohesion
between a catalog and an invoice or payment. (I have not thought
deeply about this particular domain so i am probably missing a lot of
things.)  I can imagine clients that are not doing procurement needing
access to a catalog.  For example, an inventory system updating the
"in-stock"ness of items in the catalog.

A single document type could easily be used in multiple media types.
Perhaps it would be best to have a "procurement" media type and a
separate "inventory management" media type which both include a
"catalog" document type.

Peter
<http://barelyenough.org>

Hi Jan,

Good info. Wonder if Flickr is going to give you a call? :D 

Of all the types, the Type II you list gives me the hardest time accepting. Your red box indicates that the client side is aware of the state ahead of time, thus it fails the REST test. I don't quite get this tho. I understand that if I call a single URI, and it returns me with some dynamic list of links I can call based on the representation at that time.. that I can only use those links. That should remain REST based correct?

I don't understand why, ahead of time a client might not know the possible outcomes. Let's say you call a get on /orders. It returns a list of orders. For each order you can call GET on it, PUT to update it, or DELETE. As well, you can call POST on /orders to create a new order. I am confused on why it is UN-RESTful if a client knows ahead of time that these are ALL the actions that can happen at this point. By this I mean, let's say the GET /orders did NOT return a URI to allow a user to create a new order. Ok..that's fine, the client wrapper that says order.create() simply wont work. If I am a client wrapping a RESTful api into an couple of classes to provide a java based api, so that other client users can simply use my classes and not try to figure out REST... I would check the URIs and if a user of my wrapper classes tried to call order.create(), I would simply fail immediately because the URI did not come back from the first get /orders. 

I can't imagine Amazon, Flickr or anyone would simply publish a single URI and say "Hey world.. here is the published URI.. go have fun" and then make clients guess what is possible within the realms of the API. There has got to be some sort of knowledge about what this API will allow. I think as long as it stresses in the document that a client must never assume all possible calls are available.. there should be no reason why this wouldn't work.

For example, if I go to a certain web site, I can easily jot down the list of href links I can click on. Most of the time, those are going to be the same based on a given state. If I log in, a web site lists some menus/links I can click. They are pretty much always the same thing. I could write a client side test system to automate testing of this. I might have to do something like "get me all links".. and then a "if this link.. click it.. I know it does this..". sort of thing.. so that in case I log in and a new News link is available, I can handle it, possibly based on the media type.

I guess my point is, I don't understand how a client is supposed to go into a RESTful API completely blind. There has to be some idea of what is possible with the API and that if you create an order, the possible links coming back might be these.. they may or may not all be present, but at most it's these so you can at least know ahead of time what you might have and can do.

thanks.


--- On Thu, 2/25/10, Jan Algermissen <algermissen1971@...> wrote:

From: Jan Algermissen <algermissen1971@...>
Subject: [rest-discuss] Differentiating HTTP-based APIs
To: "REST Discuss" <rest-discuss@yahoogroups.com>
Date: Thursday, February 25, 2010, 5:19 AM







 



  


    
      
      
      Hi,



I have put together a table classifying HTTP-based API-types according to the REST constraints they adhere to:



<http://nordsc. com/ext/classifi cation_of_ http_based_ apis.html>



Hope this is useful.



Jan



------------ --------- --------- -----

 Jan Algermissen, Consultant

 NORD Software Consulting



Mail: algermissen@ acm.org

 Blog: http://www.nordsc. com/blog/

 Work: http://www.nordsc. com/

------------ --------- --------- -----





    
     

    
    


 



  






      

Very good indeed. Simple, concise and to the point, things that to be
frankly are not very frequent in REST world.

I just wish, for the sake of preserving the notion that REST is a (or can be
a) multi protocol architecture style, that in some place you mentioned that
that analysis is in respect to the HTTP Uniform Interface and not to HTTP
itself. If I understood correctly, I mean.

Besides that, I was expecting some mention to POX or POX Over HTTP kind of
stuff, maybe is worth to mention in what category it falls.

Nevertheless, very nice work.

Cheers.

_________________________________________________

Melhores cumprimentos / Beir beannacht / Best regards

Ant�nio Manuel dos Santos Mota

http://card.ly/amsmota
_________________________________________________



2010/2/25 Jan Algermissen <algermissen1971@mac.com>

>
>
> Hi,
>
> I have put together a table classifying HTTP-based API-types according to
> the REST constraints they adhere to:
>
> <http://nordsc.com/ext/classification_of_http_based_apis.html>
>
> Hope this is useful.
>
> Jan
>
> -----------------------------------
> Jan Algermissen, Consultant
> NORD Software Consulting
>
> Mail: algermissen@... <algermissen%40acm.org>
> Blog: http://www.nordsc.com/blog/
> Work: http://www.nordsc.com/
> -----------------------------------
>
>  
>

On Feb 25, 2010, at 5:25 PM, Ant�nio Mota wrote:

> 
> 
> Very good indeed. Simple, concise and to the point, things that to be frankly are not very frequent in REST world.

Thanks Ant�nio!


> 
> I just wish, for the sake of preserving the notion that REST is a (or can be a) multi protocol architecture style, that in some place you mentioned that that analysis is in respect to the HTTP Uniform Interface and not to HTTP itself. If I understood correctly, I mean.

Are you saying I should not name the 4th style 'REST' but sort of 'RESTful use of HTTP' because otherwise I am mixing style (REST) and actual architectur (HTTP)?

> 
> Besides that, I was expecting some mention to POX or POX Over HTTP kind of stuff, maybe is worth to mention in what category it falls.

I do not think it relates to the classification, but I agree that it makes sense to tell people sth like "if you do POX+JAXB over HTTP you'll likely end up with a Type I API"


> 
> Nevertheless, very nice work.
> 

Thanks. The point was to put some posts in the ground to ease discussion.

Jan

> Cheers.
> 
> _________________________________________________
> 
> Melhores cumprimentos / Beir beannacht / Best regards
> 
> Ant�nio Manuel dos Santos Mota
> 
> http://card.ly/amsmota
> _________________________________________________
> 
> 
> 
> 2010/2/25 Jan Algermissen <algermissen1971@...>
>  
> Hi,
> 
> I have put together a table classifying HTTP-based API-types according to the REST constraints they adhere to:
> 
> <http://nordsc.com/ext/classification_of_http_based_apis.html>
> 
> Hope this is useful.
> 
> Jan
> 
> -----------------------------------
> Jan Algermissen, Consultant
> NORD Software Consulting
> 
> Mail: algermissen@...
> Blog: http://www.nordsc.com/blog/
> Work: http://www.nordsc.com/
> -----------------------------------
> 
> 
> 
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Actually I am doing exactly that with JAXB + XML/JSON/JSONP formats.

I modeled the links in a JPA table  and established a relationship
between the entities with this table, so the links are in the domain
model itself...

for example, when you call this URI:
http://fgaucho.dyndns.org:8080/arena-http/competition

that links element comes from the database.. serialized pure with JAXB..

For me, HATEOAS is more about the self-descriptiveness and links to
the next feasible states than the technology behind that...

* and my project is a work in progress, it is not mature yet. I am
learning a lot here in this list and this new classification sheet
will help me as benchmark :)

thanks............



On Thu, Feb 25, 2010 at 6:12 PM, Jan Algermissen
<algermissen1971@...> wrote:
>
>
> On Feb 25, 2010, at 5:57 PM, Felipe Gaucho wrote:
>
>> Other point: in your list of examples you included a set of services implementatiom and the atom pub spec...
>>
>> Please change to an atom pub implementation.. If any :)
>
> Yes, you are right - I am mixing type and instance there.
>
> Thanks (pls wait for next version)
>
> Jan
>
>
>
>>
>> On 25.02.2010, at 17:39, Jan Algermissen <algermissen1971@mac.com> wrote:
>>
>>>
>>> On Feb 25, 2010, at 5:25 PM, Ant�nio Mota wrote:
>>>
>>>>
>>>>
>>>> Very good indeed. Simple, concise and to the point, things that to be frankly are not very frequent in REST world.
>>>
>>> Thanks Ant�nio!
>>>
>>>>
>>>> I just wish, for the sake of preserving the notion that REST is a (or can be a) multi protocol architecture style, that in some place you mentioned that that analysis is in respect to the HTTP Uniform Interface and not to HTTP itself. If I understood correctly, I mean.
>>>
>>> Are you saying I should not name the 4th style 'REST' but sort of 'RESTful use of HTTP' because otherwise I am mixing style (REST) and actual architectur (HTTP)?
>>>
>>>>
>>>> Besides that, I was expecting some mention to POX or POX Over HTTP kind of stuff, maybe is worth to mention in what category it falls.
>>>
>>> I do not think it relates to the classification, but I agree that it makes sense to tell people sth like "if you do POX+JAXB over HTTP you'll likely end up with a Type I API"
>>>
>>>>
>>>> Nevertheless, very nice work.
>>>>
>>>
>>> Thanks. The point was to put some posts in the ground to ease discussion.
>>>
>>> Jan
>>>
>>>> Cheers.
>>>>
>>>> _________________________________________________
>>>>
>>>> Melhores cumprimentos / Beir beannacht / Best regards
>>>>
>>>> Ant�nio Manuel dos Santos Mota
>>>>
>>>> http://card.ly/amsmota
>>>> _________________________________________________
>>>>
>>>>
>>>>
>>>> 2010/2/25 Jan Algermissen <algermissen1971@mac.com>
>>>>
>>>> Hi,
>>>>
>>>> I have put together a table classifying HTTP-based API-types according to the REST constraints they adhere to:
>>>>
>>>> <http://nordsc.com/ext/classification_of_http_based_apis.html>
>>>>
>>>> Hope this is useful.
>>>>
>>>> Jan
>>>>
>>>> -----------------------------------
>>>> Jan Algermissen, Consultant
>>>> NORD Software Consulting
>>>>
>>>> Mail: algermissen@...
>>>> Blog: http://www.nordsc.com/blog/
>>>> Work: http://www.nordsc.com/
>>>> -----------------------------------
>>>>
>>>>
>>>>
>>>>
>>>>
>>>>
>>>
>>> -----------------------------------
>>> Jan Algermissen, Consultant
>>> NORD Software Consulting
>>>
>>> Mail: algermissen@...
>>> Blog: http://www.nordsc.com/blog/
>>> Work: http://www.nordsc.com/
>>> -----------------------------------
>>>
>>> 
>
> -----------------------------------
> Jan Algermissen, Consultant
> NORD Software Consulting
>
> Mail: algermissen@...
> Blog: http://www.nordsc.com/blog/
> Work: http://www.nordsc.com/
> -----------------------------------
>
>
>
>
>



-- 
------------------------------------------
   Felipe Ga�cho
   10+ Java Programmer
   CEJUG Senior Advisor

On Feb 25, 2010, at 5:57 PM, Felipe Gaucho wrote:

> Other point: in your list of examples you included a set of services implementatiom and the atom pub spec...
> 
> Please change to an atom pub implementation.. If any :)

Yes, you are right - I am mixing type and instance there.

Thanks (pls wait for next version)

Jan



> 
> On 25.02.2010, at 17:39, Jan Algermissen <algermissen1971@...> wrote:
> 
>> 
>> On Feb 25, 2010, at 5:25 PM, Ant�nio Mota wrote:
>> 
>>> 
>>> 
>>> Very good indeed. Simple, concise and to the point, things that to be frankly are not very frequent in REST world.
>> 
>> Thanks Ant�nio!
>> 
>>> 
>>> I just wish, for the sake of preserving the notion that REST is a (or can be a) multi protocol architecture style, that in some place you mentioned that that analysis is in respect to the HTTP Uniform Interface and not to HTTP itself. If I understood correctly, I mean.
>> 
>> Are you saying I should not name the 4th style 'REST' but sort of 'RESTful use of HTTP' because otherwise I am mixing style (REST) and actual architectur (HTTP)?
>> 
>>> 
>>> Besides that, I was expecting some mention to POX or POX Over HTTP kind of stuff, maybe is worth to mention in what category it falls.
>> 
>> I do not think it relates to the classification, but I agree that it makes sense to tell people sth like "if you do POX+JAXB over HTTP you'll likely end up with a Type I API"
>> 
>>> 
>>> Nevertheless, very nice work.
>>> 
>> 
>> Thanks. The point was to put some posts in the ground to ease discussion.
>> 
>> Jan
>> 
>>> Cheers.
>>> 
>>> _________________________________________________
>>> 
>>> Melhores cumprimentos / Beir beannacht / Best regards
>>> 
>>> Ant�nio Manuel dos Santos Mota
>>> 
>>> http://card.ly/amsmota
>>> _________________________________________________
>>> 
>>> 
>>> 
>>> 2010/2/25 Jan Algermissen <algermissen1971@...>
>>> 
>>> Hi,
>>> 
>>> I have put together a table classifying HTTP-based API-types according to the REST constraints they adhere to:
>>> 
>>> <http://nordsc.com/ext/classification_of_http_based_apis.html>
>>> 
>>> Hope this is useful.
>>> 
>>> Jan
>>> 
>>> -----------------------------------
>>> Jan Algermissen, Consultant
>>> NORD Software Consulting
>>> 
>>> Mail: algermissen@...
>>> Blog: http://www.nordsc.com/blog/
>>> Work: http://www.nordsc.com/
>>> -----------------------------------
>>> 
>>> 
>>> 
>>> 
>>> 
>>> 
>> 
>> -----------------------------------
>> Jan Algermissen, Consultant
>> NORD Software Consulting
>> 
>> Mail: algermissen@...
>> Blog: http://www.nordsc.com/blog/
>> Work: http://www.nordsc.com/
>> -----------------------------------
>> 
>> 

-----------------------------------
Jan Algermissen, Consultant
NORD Software Consulting

Mail: algermissen@...
Blog: http://www.nordsc.com/blog/
Work: http://www.nordsc.com/
-----------------------------------

On Feb 25, 2010, at 4:57 PM, Kevin Duffey wrote:

> Hi Jan,
> 
> Good info. Wonder if Flickr is going to give you a call? :D

Well....it had to come down on *somebody* :-)

> 
> Of all the types, the Type II you list gives me the hardest time accepting. Your red box indicates that the client side is aware of the state ahead of time, thus it fails the REST test.

Yes, correct.

> I don't quite get this tho. I understand that if I call a single URI, and it returns me with some dynamic list of links I can call based on the representation at that time.. that I can only use those links. That should remain REST based correct?

Yes, as long as the representation that contains the links has a specific media type (that defines the meaning of the links).

> 
> I don't understand why, ahead of time a client might not know the possible outcomes.

Because the hypermedia constraint constrains that :-) The client MUST not assume what is coming back - only discover it. That is REST's essence if you want.

Because it enables the server to evolve without asking the client what it assmes.

> Let's say you call a get on /orders. It returns a list of orders.

.. maybe ...

> For each order you can call GET on it,

.. maybe ...

> PUT to update it, or DELETE.

... maybe ...

Th epoint being: if you *find* a link to an order that has the semantics (from a media type or link rel specs) that these methods can be called *then* you know you can do that with an order resource. (The 'edit' link of AtomPub does something like that).

As long as the server does not tell you, you cannot assume that you can do what you describe.

> As well, you can call POST on /orders to create a new order.

If some hypermedia tells you that about /orders - then you can go ahead and POST. You need to discover that information.

> I am confused on why it is UN-RESTful if a client knows ahead of time that these are ALL the actions that can happen at this point.

It is unESTful because the client would break if the server chooses to change.

> By this I mean, let's say the GET /orders did NOT return a URI to allow a user to create a new order. Ok..that's fine, the client wrapper that says order.create() simply wont work.

Right. The current state machine you are 'walking through' does not allow you to do that. Might be different next time.

[Side note: the essential thing to understand here is that in a decentralized environment there can never be a guarrantee that something works at some point because you do not control the server. Hiding the decentralization by an OO API doesnot change that - it just causes the false impression because the IDL specifies that method on class orders. IDLs are for APIs of compoenents that are inside the same 'piece of software'.

REST only emphasizes that the client should plan for the create link not to be there.]


> If I am a client wrapping a RESTful api into an couple of classes to provide a java based api,

That is generally a bad idea - do not hide the network!

> so that other client users can simply use my classes and not try to figure out REST... I would check the URIs and if a user of my wrapper classes tried to call order.create(), I would simply fail immediately because the URI did not come back from the first get /orders.

This would again just lead you deveoper to think being able to create would be the normal case.


> 
> I can't imagine Amazon, Flickr or anyone would simply publish a single URI and say "Hey world.. here is the published URI.. go have fun" and then make clients guess what is possible within the realms of the API.

The clients need to know up front what the media types are that the service uses. You need *some* information to code the client.

See http://www.nordsc.com/blog/?p=382 (and previous blogs on that issue)

> There has got to be some sort of knowledge about what this API will allow. I think as long as it stresses in the document that a client must never assume all possible calls are available.. there should be no reason why this wouldn't work.

Right. See above.

> 
> For example, if I go to a certain web site, I can easily jot down the list of href links I can click on. Most of the time, those are going to be the same based on a given state. If I log in, a web site lists some menus/links I can click. They are pretty much always the same thing. I could write a client side test system to automate testing of this. I might have to do something like "get me all links".. and then a "if this link.. click it.. I know it does this..". sort of thing.. so that in case I log in and a new News link is available, I can handle it, possibly based on the media type.

This assumes you have the service instance before you code the client. That model would work on the Web (learing about the service by inspection) but it does not work inside the enterprise because those people usually want to develop in parallel :-)

> 
> I guess my point is, I don't understand how a client is supposed to go into a RESTful API completely blind.

See above - you need to know the media types.

> There has to be some idea of what is possible with the API and that if you create an order, the possible links coming back might be these.. they may or may not all be present, but at most it's these so you can at least know ahead of time what you might have and can do.

HTH,

Jan

> 
> thanks.
> 
> 
> --- On Thu, 2/25/10, Jan Algermissen <algermissen1971@...> wrote:
> 
> From: Jan Algermissen <algermissen1971@...>
> Subject: [rest-discuss] Differentiating HTTP-based APIs
> To: "REST Discuss" <rest-discuss@yahoogroups.com>
> Date: Thursday, February 25, 2010, 5:19 AM
> 
> Hi,
> 
> I have put together a table classifying HTTP-based API-types according to the REST constraints they adhere to:
> 
> <http://nordsc. com/ext/classifi cation_of_ http_based_ apis.html>
> 
> Hope this is useful.
> 
> Jan
> 
> ------------ --------- --------- -----
> Jan Algermissen, Consultant
> NORD Software Consulting
> 
> Mail: algermissen@ acm.org
> Blog: http://www.nordsc. com/blog/
> Work: http://www.nordsc. com/
> ------------ --------- --------- -----
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

2010/2/25 Jan Algermissen <algermissen1971@...>:
>>
>> I just wish, for the sake of preserving the notion that REST is a (or can be a) multi protocol architecture style, that in some place you mentioned that that analysis is in respect to the HTTP Uniform Interface and not to HTTP itself. If I understood correctly, I mean.
>
> Are you saying I should not name the 4th style 'REST' but sort of 'RESTful use of HTTP' because otherwise I am mixing style (REST) and actual architectur (HTTP)?
>

Well, not quite, I think it is REST and you do well in calling it that
without ambiguity. What I was saying is that if you constraint other
protocols to use the same interface as HTTP, then your analysis apply
to those other protocols based architectures as well. So it was worth
mentioning that...

>>
>> Besides that, I was expecting some mention to POX or POX Over HTTP kind of stuff, maybe is worth to mention in what category it falls.
>
> I do not think it relates to the classification, but I agree that it makes sense to tell people sth like "if you do POX+JAXB over HTTP you'll likely end up with a Type I API"
>

Yes, it was in that sense, of pointing as example, that I was referring to.



Cheers.

On Feb 25, 2010, at 5:50 PM, Felipe Gaucho wrote:

> You can use jaxb and use xml and get a restful service...
> There is no mandatory link between these technologies and "non-rest" style...

Right, sorry to imply that. OTH, there will often be no 1:1 mapping between domain object (that's how I understood POJO) so if you use JAXB on your POJO you'll rather have a serialized domain object than 'resource representation'

But I now saw my error: I thought of POJO, not POX. Sorry.


> 
> Excellent sumary ... Congrats...


Thanks,
Jan


> 
> On 25.02.2010, at 17:39, Jan Algermissen <algermissen1971@...> wrote:
> 
>> 
>> On Feb 25, 2010, at 5:25 PM, Ant�nio Mota wrote:
>> 
>>> 
>>> 
>>> Very good indeed. Simple, concise and to the point, things that to be frankly are not very frequent in REST world.
>> 
>> Thanks Ant�nio!
>> 
>>> 
>>> I just wish, for the sake of preserving the notion that REST is a (or can be a) multi protocol architecture style, that in some place you mentioned that that analysis is in respect to the HTTP Uniform Interface and not to HTTP itself. If I understood correctly, I mean.
>> 
>> Are you saying I should not name the 4th style 'REST' but sort of 'RESTful use of HTTP' because otherwise I am mixing style (REST) and actual architectur (HTTP)?
>> 
>>> 
>>> Besides that, I was expecting some mention to POX or POX Over HTTP kind of stuff, maybe is worth to mention in what category it falls.
>> 
>> I do not think it relates to the classification, but I agree that it makes sense to tell people sth like "if you do POX+JAXB over HTTP you'll likely end up with a Type I API"
>> 
>>> 
>>> Nevertheless, very nice work.
>>> 
>> 
>> Thanks. The point was to put some posts in the ground to ease discussion.
>> 
>> Jan
>> 
>>> Cheers.
>>> 
>>> _________________________________________________
>>> 
>>> Melhores cumprimentos / Beir beannacht / Best regards
>>> 
>>> Ant�nio Manuel dos Santos Mota
>>> 
>>> http://card.ly/amsmota
>>> _________________________________________________
>>> 
>>> 
>>> 
>>> 2010/2/25 Jan Algermissen <algermissen1971@...>
>>> 
>>> Hi,
>>> 
>>> I have put together a table classifying HTTP-based API-types according to the REST constraints they adhere to:
>>> 
>>> <http://nordsc.com/ext/classification_of_http_based_apis.html>
>>> 
>>> Hope this is useful.
>>> 
>>> Jan
>>> 
>>> -----------------------------------
>>> Jan Algermissen, Consultant
>>> NORD Software Consulting
>>> 
>>> Mail: algermissen@...
>>> Blog: http://www.nordsc.com/blog/
>>> Work: http://www.nordsc.com/
>>> -----------------------------------
>>> 
>>> 
>>> 
>>> 
>>> 
>>> 
>> 
>> -----------------------------------
>> Jan Algermissen, Consultant
>> NORD Software Consulting
>> 
>> Mail: algermissen@...
>> Blog: http://www.nordsc.com/blog/
>> Work: http://www.nordsc.com/
>> -----------------------------------
>> 
>> 

-----------------------------------
Jan Algermissen, Consultant
NORD Software Consulting

Mail: algermissen@...
Blog: http://www.nordsc.com/blog/
Work: http://www.nordsc.com/
-----------------------------------

On Thu, Feb 25, 2010 at 9:12 AM, Jan Algermissen
<algermissen1971@...> wrote:
>
> On Feb 25, 2010, at 5:50 PM, Felipe Gaucho wrote:
>
>> You can use jaxb and use xml and get a restful service...
>> There is no mandatory link between these technologies and "non-rest" style...
>
> Right, sorry to imply that. OTH, there will often be no 1:1 mapping between domain object (that's how I understood POJO) so if you use JAXB on your POJO you'll rather have a serialized domain object than 'resource representation'
>

When using JAX-RS, I'm finding myself more and more often building a
set of JAXB annotated classes that directly represent my resources,
separate from the classes that might represent my domain tier (with,
perhaps, JPA or Hibernate annotations on them).  Besides the fact that
this means I don't have to write all of the boring serialization code,
it has some other benefits:

- Both XML and JSON serialization, nearly for free.

- Ability to include properties for however I'm going to represent
  links (which don't belong in the domain model at all).

- Ability to include properties for related resources (either individual
  child beans or collections of them), for which JAXB does a
  slick job of including as nested sub-elements, versus
  entity beans that are typically associated with only one table.

- Ability to write business logic that is natural to Java
  developers used to beans oriented development,
  independent of the fact that this resource was received
  (or will be sent) across some HTTP or other transport.

- Ablity to write much better unit and functional tests that can
  reason about the resource model (independent of how the
  resources got received from a client or synthesized from my
  database domain objects), with all the usual
  benefits of a strongly typed language (versus using
  XPath or poking through some JSON data structure
  with string based keys and hoping I spelled the keys right).

It's good stuff for Java developers.

Craig

Hello,

Bruno Harbulot recently mentioned this thread, so I thought I'd join
the mailing list and contribute a tidbit to it.

I recently published a proof of concept tool which implements
form-based HTTP authentication using a combination of XMLHttpRequest
objects and response code tricks.  It seems to work reliably in the
four most popular browsers.  Code is here:
  http://www.vsecurity.com/download/tools/fbha-poc_0.1.zip

This work was inspired by the work I did previously on the
difficulties of securing cookies and some of the benefits of HTTP
digest authentication:
  http://www.vsecurity.com/download/papers/WeaningTheWebOffOfSessionCookies.pdf
  http://www.vsecurity.com/download/papers/HTTPDigestIntegrity.pdf

Thanks,
tim

On Feb 25, 2010, at 8:37 PM, Craig McClanahan wrote:

> On Thu, Feb 25, 2010 at 9:12 AM, Jan Algermissen
> <algermissen1971@...> wrote:
>> 
>> On Feb 25, 2010, at 5:50 PM, Felipe Gaucho wrote:
>> 
>>> You can use jaxb and use xml and get a restful service...
>>> There is no mandatory link between these technologies and "non-rest" style...
>> 
>> Right, sorry to imply that. OTH, there will often be no 1:1 mapping between domain object (that's how I understood POJO) so if you use JAXB on your POJO you'll rather have a serialized domain object than 'resource representation'
>> 
> 
> When using JAX-RS, I'm finding myself more and more often building a
> set of JAXB annotated classes that directly represent my resources,

That's a good approach. If you are using specific media types that means the annotated classes map to media types or individual doctypes of a media type (Apache Abdera for example).


> separate from the classes that might represent my domain tier (with,
> perhaps, JPA or Hibernate annotations on them).  Besides the fact that
> this means I don't have to write all of the boring serialization code,
> it has some other benefits:



> 
> - Both XML and JSON serialization, nearly for free.
> 
> - Ability to include properties for however I'm going to represent
>  links (which don't belong in the domain model at all).
> 
> - Ability to include properties for related resources (either individual
>  child beans or collections of them), for which JAXB does a
>  slick job of including as nested sub-elements, versus
>  entity beans that are typically associated with only one table.
> 
> - Ability to write business logic that is natural to Java
>  developers used to beans oriented development,
>  independent of the fact that this resource was received
>  (or will be sent) across some HTTP or other transport.
> 
> - Ablity to write much better unit and functional tests that can
>  reason about the resource model (independent of how the
>  resources got received from a client or synthesized from my
>  database domain objects), with all the usual
>  benefits of a strongly typed language (versus using
>  XPath or poking through some JSON data structure
>  with string based keys and hoping I spelled the keys right).
> 
> It's good stuff for Java developers.

Good points, thanks.

Jan


> 
> Craig
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Maybe I am doing this wrong, but what I do is usually I put my JAXB generated XSD model objects in a separate project. I then build this jar and copy it to my web-inf/lib of my REST/ejb based application. I use the JAXB model objects in my Jersey resources, as well as in my session beans to convert from the JAXB bean to the entity bean. There is probably an easier way to do this, but presently I simply do a eb.setXxx(jb.getXxx()) method for each item I wish to copy to the entity, or from it when going back the other way. JEE6 makes this a breeze to work with.

I've not yet looked into the ramifications of scaling, caching, etc.. I am hoping that the EE6 containers do a lot of this for me for free these days. Being stateless in the session bean and REST service, and only the entity persists when required, I would hope that I should be able to scale quite rapidly and easily, the back end DB being the most difficult probably to deal with.

--- On Thu, 2/25/10, Craig McClanahan <craigmcc@...> wrote:

From: Craig McClanahan <craigmcc@...>
Subject: Re: [rest-discuss] Differentiating HTTP-based APIs
To: "Jan Algermissen" <algermissen1971@...>
Cc: "Felipe Gaucho" <fgaucho@gmail.com>, "REST Discuss" <rest-discuss@yahoogroups.com>
Date: Thursday, February 25, 2010, 11:37 AM







 



  


    
      
      
      On Thu, Feb 25, 2010 at 9:12 AM, Jan Algermissen

<algermissen1971@ mac.com> wrote:

>

> On Feb 25, 2010, at 5:50 PM, Felipe Gaucho wrote:

>

>> You can use jaxb and use xml and get a restful service...

>> There is no mandatory link between these technologies and "non-rest" style...

>

> Right, sorry to imply that. OTH, there will often be no 1:1 mapping between domain object (that's how I understood POJO) so if you use JAXB on your POJO you'll rather have a serialized domain object than 'resource representation'

>



When using JAX-RS, I'm finding myself more and more often building a

set of JAXB annotated classes that directly represent my resources,

separate from the classes that might represent my domain tier (with,

perhaps, JPA or Hibernate annotations on them).  Besides the fact that

this means I don't have to write all of the boring serialization code,

it has some other benefits:



- Both XML and JSON serialization, nearly for free.



- Ability to include properties for however I'm going to represent

  links (which don't belong in the domain model at all).



- Ability to include properties for related resources (either individual

  child beans or collections of them), for which JAXB does a

  slick job of including as nested sub-elements, versus

  entity beans that are typically associated with only one table.



- Ability to write business logic that is natural to Java

  developers used to beans oriented development,

  independent of the fact that this resource was received

  (or will be sent) across some HTTP or other transport.



- Ablity to write much better unit and functional tests that can

  reason about the resource model (independent of how the

  resources got received from a client or synthesized from my

  database domain objects), with all the usual

  benefits of a strongly typed language (versus using

  XPath or poking through some JSON data structure

  with string based keys and hoping I spelled the keys right).



It's good stuff for Java developers.



Craig



    
     

    
    


 



  






      

There is only 1 drawback in your solution: JAXB unfortunately doesn't allow
you to add extra annotations in the generated files, so you need to manually
manage the ORM.. Despite that there is a large community that believes that
isolating domain model from business model is a better approach than mix
them together.. (a long Java Design Patterns discussion I will avoid here)

One alternative is to use the package-info file to manage the namespaces and
do annotate the model classes directly.. it is more programmatic approach
but you preserve the namespaces as well... and then you can annotate the
classes also as Entities and you get the DB roundtrip for free.. and Jersey
+ CDI com inject the EntityManager in your service layer if you want... and
it scales like hell :) eheh


the problem still remains: how to control the hypermedia workflow.. I've
seen people adopting custom annotations and several other tricks but so far
a stable solution didn't emerged ... we are waiting your best thoughts :)




On Fri, Feb 26, 2010 at 3:33 AM, Kevin Duffey <andjarnic@...> wrote:

>
>
>
> Maybe I am doing this wrong, but what I do is usually I put my JAXB
> generated XSD model objects in a separate project. I then build this jar and
> copy it to my web-inf/lib of my REST/ejb based application. I use the JAXB
> model objects in my Jersey resources, as well as in my session beans to
> convert from the JAXB bean to the entity bean. There is probably an easier
> way to do this, but presently I simply do a eb.setXxx(jb.getXxx()) method
> for each item I wish to copy to the entity, or from it when going back the
> other way. JEE6 makes this a breeze to work with.
>
> I've not yet looked into the ramifications of scaling, caching, etc.. I am
> hoping that the EE6 containers do a lot of this for me for free these days.
> Being stateless in the session bean and REST service, and only the entity
> persists when required, I would hope that I should be able to scale quite
> rapidly and easily, the back end DB being the most difficult probably to
> deal with.
>
> --- On *Thu, 2/25/10, Craig McClanahan <craigmcc@...>* wrote:
>
>
> From: Craig McClanahan <craigmcc@...>
> Subject: Re: [rest-discuss] Differentiating HTTP-based APIs
> To: "Jan Algermissen" <algermissen1971@...>
> Cc: "Felipe Gaucho" <fgaucho@...>, "REST Discuss" <
> rest-discuss@yahoogroups.com>
> Date: Thursday, February 25, 2010, 11:37 AM
>
>
>
>
> On Thu, Feb 25, 2010 at 9:12 AM, Jan Algermissen
> <algermissen1971@ mac.com <http://mc/compose?to=algermissen1971%40mac.com>>
> wrote:
> >
> > On Feb 25, 2010, at 5:50 PM, Felipe Gaucho wrote:
> >
> >> You can use jaxb and use xml and get a restful service...
> >> There is no mandatory link between these technologies and "non-rest"
> style...
> >
> > Right, sorry to imply that. OTH, there will often be no 1:1 mapping
> between domain object (that's how I understood POJO) so if you use JAXB on
> your POJO you'll rather have a serialized domain object than 'resource
> representation'
> >
>
> When using JAX-RS, I'm finding myself more and more often building a
> set of JAXB annotated classes that directly represent my resources,
> separate from the classes that might represent my domain tier (with,
> perhaps, JPA or Hibernate annotations on them). Besides the fact that
> this means I don't have to write all of the boring serialization code,
> it has some other benefits:
>
> - Both XML and JSON serialization, nearly for free.
>
> - Ability to include properties for however I'm going to represent
> links (which don't belong in the domain model at all).
>
> - Ability to include properties for related resources (either individual
> child beans or collections of them), for which JAXB does a
> slick job of including as nested sub-elements, versus
> entity beans that are typically associated with only one table.
>
> - Ability to write business logic that is natural to Java
> developers used to beans oriented development,
> independent of the fact that this resource was received
> (or will be sent) across some HTTP or other transport.
>
> - Ablity to write much better unit and functional tests that can
> reason about the resource model (independent of how the
> resources got received from a client or synthesized from my
> database domain objects), with all the usual
> benefits of a strongly typed language (versus using
> XPath or poking through some JSON data structure
> with string based keys and hoping I spelled the keys right).
>
> It's good stuff for Java developers.
>
> Craig
>
>
>  
>



-- 
------------------------------------------
  Felipe Ga�cho
  10+ Java Programmer
  CEJUG Senior Advisor

2010/2/25 Felipe Ga�cho <fgaucho@...>

>
>
> There is only 1 drawback in your solution: JAXB unfortunately doesn't allow
> you to add extra annotations in the generated files, so you need to manually
> manage the ORM.. Despite that there is a large community that believes that
> isolating domain model from business model is a better approach than mix
> them together.. (a long Java Design Patterns discussion I will avoid here)
>
> You're missing a key feature of what both Kevin and I said ... use
*different* classes for the *resource* domain model and the *business*
domain model.  Then, each kind of class can have the annotations that are
relevant for that tier.  If you think about an MVC style architecture, and
take the point of view of the server developer, the classes representing
your resources are part of the view tier, while the classes representing the
business domain are part of the model tier.

The value of putting the resource model classes in a separate library is
that, if you use one of several JAX-RS implementations like Jersey, you can
leverage the same JAX-RS infrastructure for serialization on the client side
(when you have a Java based client) as on the server side, thus reducing
development effort and potential for impedance mismatches.  But that is
orthogonal to the idea that the two models are often different.

> One alternative is to use the package-info file to manage the namespaces
> and do annotate the model classes directly.. it is more programmatic
> approach but you preserve the namespaces as well... and then you can
> annotate the classes also as Entities and you get the DB roundtrip for
> free.. and Jersey + CDI com inject the EntityManager in your service layer
> if you want... and it scales like hell :) eheh
>
>
> the problem still remains: how to control the hypermedia workflow.. I've
> seen people adopting custom annotations and several other tricks but so far
> a stable solution didn't emerged ... we are waiting your best thoughts :)
>
> Managing workflow, like obeying the hypermedia constraint, is a view tier
concern (from the point of view of a server side developer).  All you need
to do is define the appropriate hypermedia links into your representations
(and therefore into your resource model classes if you're using Java and
JAX-RS), and populate them appropriately when a JAX-RS resource method is
called.  In the mean time, your JPA or Hibernate classes representing the
business domain model can remain serenely oblivious to things like URIs.
That's a good thing, because a REST API is typically not the only way that
such business model objects get manipulated.

Self-test time:  are you storing URIs in your database?  If so, think
again.  Are you using values (like primary keys) from your business domain
model classes in order to calculate the URIs that show up in your resource
model classes?  That's OK, although you should not feel constrained to build
URIs in the fashion you typically see
(".../customers/{customerID}/orders/{orderID}").  The only part of the
server side logic that cares about the generated URIs should be the logic
that processes incoming requests from those generated URIs.  In the case of
a JAX-RS based server application, that "care" is expressed by @Path
annotations.  Fortunately, JAX-RS also has APIs to "reverse engineer" an
appropriate resource URI from the @Path annotations that are present in many
cases, so if you leverage this functionality when generating URIs in your
resource representations, you still have to change only one thing -- the
@Path annotations -- to change the URIs included in your representations.

In the shopping cart use case (no, I don't care if some people don't like it
as an example :-), a well designed REST API should *not* define a URI
template like "/checkout" that accepts a POST with a shopping cart
representation.  Instead, the representation of the cart last sent by the
server should include a URI you can POST to to initiate checkout on *this*
shopping cart instance (and it should be included only if the cart is in a
state that is appropriate for checkout) ... for security, you're much better
off if the server generates a random string based URI for this, which
expires after a short amount of time, to reduce the opportunity for client
initiated mischief.

A properly coded client, then, will need to understand how to extract this
URI from the representation, and understand that it needs to do a POST with
the current cart contents as its request body.  But, as far as the client is
concerned, the URI itself is an opaque string.

Craig

> You're missing a key feature of what both Kevin and I said ... use
> *different* classes for the *resource* domain model and the *business*
> domain model.

yes, I am aware about that... but the effort to maintain the mapping
between those models generates an extra and unnecessary development
effort ,.... I also noticed some people having a third model when the
data will be rendered in the presentation layer.. (a managedbean or
other component..)... My experiment is looking to reduce the amount of
effort required to synchronize all those models, having only one
model.. and it works fine and the performance is better and
maintenance effort much less than the traditional MVC design...


> Then, each kind of class can have the annotations that are relevant for that tier.

Usually the classes are identical and you are just including a copy
layer to transfer data between them :)

> Managing workflow, like obeying the hypermedia constraint, is a view tier concern (from the point of view of a server side developer).

May be, may be not.. in my case the model contains the sate of the
application, so it is a business concern :)

> That's a good thing, because a REST API is typically not the only way that
> such business model objects get manipulated.

yes, but the effort to manage the hypermedia just in time makes the
whole application much slower.. and it is a repettive task.. that is
one of the reasons that motivated me to push the links in the
database....

> Self-test time:� are you storing URIs in your database?

yes. The sate of the application is persistent :) and scales quite
well since I don't need to recalculate the sate on every request..
(ok, memcache can help a bit, but anyway... the hypermedia engine it
is the heavy part of the request - eliminating that I have much faster
services)

> a JAX-RS based server application, that "care" is expressed by @Path

I am experimenting with that idea.. in order to use regular
expressions or other DSL facilty to manipulate the final URI
dinamically.. perhaps storing just the tail of the URI in the databse
or other format of information that lead me a chance to produce the
external representation by demand.. this part is my current
research...... (I prefer the "experimentation" word since I am not a
formal researcher..)

> @Path annotations -- to change the URIs included in your representations.

yes, but you need to iterate over the collections and change manually
each URI, what can lead you to manipulate thousand of strings before
to respond to the client.. this part scares me... (think about a
collection with 100 elements, each with 20 URIs)

> In the shopping cart use case (no, I don't care if some people don't like it
> as an example :-), a well designed REST API should *not* define a URI
> template like "/checkout" that accepts a POST with a shopping cart

That is a basic REST principle .. and it is not related to the way you
store or calculate the URIs...

> concerned, the URI itself is an opaque string.

yes......

thanks for your feedback... interesting.. I will keep thinking about
your thoughts....


  Felipe Ga�cho

excellent points.. I will consider that...

2010/2/26 Craig McClanahan <craigmcc@...>:
> 2010/2/25 Felipe Ga�cho <fgaucho@...>:
>>> You're missing a key feature of what both Kevin and I said ... use
>>> *different* classes for the *resource* domain model and the *business*
>>> domain model.
>>
>> yes, I am aware about that... but the effort to maintain the mapping
>> between those models generates an extra and unnecessary development
>> effort ,.... I also noticed some people having a third model when the
>> data will be rendered in the presentation layer.. (a managedbean or
>> other component..)... My experiment is looking to reduce the amount of
>> effort required to synchronize all those models, having only one
>> model.. and it works fine and the performance is better and
>> maintenance effort much less than the traditional MVC design...
>
> In your business domain objects, do you store the CSS style class that
> should be used to display this object in a browser? �Of course not:
>
> * The *name* of the style class is totally up to the designer.
>
> * Do *you* know any designers that care about backwards compatibility
> of style names? �I don't either ...
> �but I don't care, as long as the designer updates all the
> corresponding HTML pages when the style name changes.
>
> * Style names can be changed at any time (for example, when you refresh
> �the look and feel characteristics of your website).
>
> * And, of course, there is normally more than one webapp
> �that needs to be able to render this business domain object,
> �so having only one style name would not be useful.
>
> The same principles apply to designing resource representations -- we
> should assume that there will be more than one representation that
> includes this particular object, and more than one RESTful application
> that needs to provide access to it, so assuming any *single* approach
> is not likely to help all our users.
>
>>
>>
>>> Then, each kind of class can have the annotations that are relevant for that tier.
>>
>> Usually the classes are identical and you are just including a copy
>> layer to transfer data between them :)
>>
>>> Managing workflow, like obeying the hypermedia constraint, is a view tier concern (from the point of view of a server side developer).
>>
>> May be, may be not.. in my case the model contains the sate of the
>> application, so it is a business concern :)
>>
>
> There is pretty much always more than one application needing your
> data, so it's more than one business concern :-). �Ideally, you can
> share the business domain objects across these applications, but the
> reality is you'll need multiple RESTful resource representations that
> include data from these business domain objects, for the same reason
> that you will need multiple HTML representations (even within the same
> webapp, how many different pages include information from particular
> domain objects?). �One size does not fit all.
>
>>> That's a good thing, because a REST API is typically not the only way that
>>> such business model objects get manipulated.
>>
>> yes, but the effort to manage the hypermedia just in time makes the
>> whole application much slower.. and it is a repettive task.. that is
>> one of the reasons that motivated me to push the links in the
>> database....
>>
>>> Self-test time:� are you storing URIs in your database?
>>
>> yes. The sate of the application is persistent :) and scales quite
>> well since I don't need to recalculate the sate on every request..
>> (ok, memcache can help a bit, but anyway... the hypermedia engine it
>> is the heavy part of the request - eliminating that I have much faster
>> services)
>
> Scale for one application is nice (although I'm waiting for your
> benchmarks to show that the overhead of calculating URIs dynamically
> is crushing, given how cheap CPU time is versus other server side
> resources). �How about scale for multiple applications?
>
> Oh, you only have one? �Good for you! �But that's not a particularly
> common problem domain.
>
>>
>>> a JAX-RS based server application, that "care" is expressed by @Path
>>
>> I am experimenting with that idea.. in order to use regular
>> expressions or other DSL facilty to manipulate the final URI
>> dinamically.. perhaps storing just the tail of the URI in the databse
>> or other format of information that lead me a chance to produce the
>> external representation by demand.. this part is my current
>> research...... (I prefer the "experimentation" word since I am not a
>> formal researcher..)
>>
>
> Please think about the idea that the same business domain resources
> may need to be exposed by different applications, using different
> resource representations, and different URI schemes, all at the same
> time. �Or, even within the same application, exposed in different
> pages (web app) or resources (RESTful web service) at the same time.
>
> Personal history lesson -- when I was first learning web development
> (mid-late 1990s), I figured "why not have a toHTML() method on all my
> Java business domain model classes"? �It quickly became clear that
> different pages within the same app, as well as different apps, needed
> different HTML representations of the same business objects. �Indeed,
> this realization was one of the motivating factors that led to the
> creation of Struts.
>
> The same is true for RESTful resource representations. �There will be
> more than one representation that requires information from a
> particular business domain model object, as well as more than one
> application (each with their own resource and representation
> requirements).
>
> In MVC terms: �Model classes != View classes.
>
>>> @Path annotations -- to change the URIs included in your representations.
>>
>> yes, but you need to iterate over the collections and change manually
>> each URI, what can lead you to manipulate thousand of strings before
>> to respond to the client.. this part scares me... (think about a
>> collection with 100 elements, each with 20 URIs)
>
> For amusement, you should go grab a raw Atom or RSS feed �from a busy
> feed source (I use Google Reader for my feed aggregator, but the same
> principle applies to anyone who provides feeds) and see how many URIs
> are included. � And, funny thing, none of the apps that *created* that
> content had any idea that *I* would be aggregating their feeds, via
> Google Reader, for my own use.
>
> URIs in RESTful web services are a view tier concern, just like CSS style names.
>
>>
>>> In the shopping cart use case (no, I don't care if some people don't like it
>>> as an example :-), a well designed REST API should *not* define a URI
>>> template like "/checkout" that accepts a POST with a shopping cartURI
>>
>> That is a basic REST principle .. and it is not related to the way you
>> store or calculate the URIs...
>>
>
> Unfortunately, *lots* of theoretically "RESTful API" specifications
> include instructions on how to calculate the URI for a particular
> operation (versus telling the client "get the URI you need from the
> current representation of the resource.). �And I'm as guilty as anyone
> else at violating the hypermedia constraint this way, in my earlier
> work. �But, my point in this particular scenario was, assuming that
> there was a single URI for "checkout", for *all* shopping carts, is
> technically feasible, but not a good idea.
>
>>> concerned, the URI itself is an opaque string.
>>
>> yes......
>>
>> thanks for your feedback... interesting.. I will keep thinking about
>> your thoughts....
>>
>>
>> �Felipe Ga�cho
>>
>
> Craig
>



-- 
------------------------------------------
   Felipe Ga�cho
   10+ Java Programmer
   CEJUG Senior Advisor

other point:

if two distinct application will have different machine states, then
the state of the resources will be different, and they cannot share
the same database, right  ? because eventually the attributes of the
resources will be in different states, isn't it ?

the analogy with MVC and web application views doesn't apply here.. as
far I can see.........

2010/2/26 Felipe Ga�cho <fgaucho@...>:
> just a question about your domain model sharing:
>
> and what about the code ?
>
> If you code the whole engine logic in a code, and you need a second
> application to access the same data, you will need to recode the
> engine logic again ?
>
> ok, we all think about "reuse of components", but so far I've seen
> ugly hack in the code to simulate the hypermedia engine and that's
> what I am trying to do better.. but your points are good.. I will
> digest them and try to incorporate the best I can in my design
> here.....
>
> 2010/2/26 Felipe Ga�cho <fgaucho@...>:
>> excellent points.. I will consider that...
>>
>> 2010/2/26 Craig McClanahan <craigmcc@...>:
>>> 2010/2/25 Felipe Ga�cho <fgaucho@...>:
>>>>> You're missing a key feature of what both Kevin and I said ... use
>>>>> *different* classes for the *resource* domain model and the *business*
>>>>> domain model.
>>>>
>>>> yes, I am aware about that... but the effort to maintain the mapping
>>>> between those models generates an extra and unnecessary development
>>>> effort ,.... I also noticed some people having a third model when the
>>>> data will be rendered in the presentation layer.. (a managedbean or
>>>> other component..)... My experiment is looking to reduce the amount of
>>>> effort required to synchronize all those models, having only one
>>>> model.. and it works fine and the performance is better and
>>>> maintenance effort much less than the traditional MVC design...
>>>
>>> In your business domain objects, do you store the CSS style class that
>>> should be used to display this object in a browser? �Of course not:
>>>
>>> * The *name* of the style class is totally up to the designer.
>>>
>>> * Do *you* know any designers that care about backwards compatibility
>>> of style names? �I don't either ...
>>> �but I don't care, as long as the designer updates all the
>>> corresponding HTML pages when the style name changes.
>>>
>>> * Style names can be changed at any time (for example, when you refresh
>>> �the look and feel characteristics of your website).
>>>
>>> * And, of course, there is normally more than one webapp
>>> �that needs to be able to render this business domain object,
>>> �so having only one style name would not be useful.
>>>
>>> The same principles apply to designing resource representations -- we
>>> should assume that there will be more than one representation that
>>> includes this particular object, and more than one RESTful application
>>> that needs to provide access to it, so assuming any *single* approach
>>> is not likely to help all our users.
>>>
>>>>
>>>>
>>>>> Then, each kind of class can have the annotations that are relevant for that tier.
>>>>
>>>> Usually the classes are identical and you are just including a copy
>>>> layer to transfer data between them :)
>>>>
>>>>> Managing workflow, like obeying the hypermedia constraint, is a view tier concern (from the point of view of a server side developer).
>>>>
>>>> May be, may be not.. in my case the model contains the sate of the
>>>> application, so it is a business concern :)
>>>>
>>>
>>> There is pretty much always more than one application needing your
>>> data, so it's more than one business concern :-). �Ideally, you can
>>> share the business domain objects across these applications, but the
>>> reality is you'll need multiple RESTful resource representations that
>>> include data from these business domain objects, for the same reason
>>> that you will need multiple HTML representations (even within the same
>>> webapp, how many different pages include information from particular
>>> domain objects?). �One size does not fit all.
>>>
>>>>> That's a good thing, because a REST API is typically not the only way that
>>>>> such business model objects get manipulated.
>>>>
>>>> yes, but the effort to manage the hypermedia just in time makes the
>>>> whole application much slower.. and it is a repettive task.. that is
>>>> one of the reasons that motivated me to push the links in the
>>>> database....
>>>>
>>>>> Self-test time:� are you storing URIs in your database?
>>>>
>>>> yes. The sate of the application is persistent :) and scales quite
>>>> well since I don't need to recalculate the sate on every request..
>>>> (ok, memcache can help a bit, but anyway... the hypermedia engine it
>>>> is the heavy part of the request - eliminating that I have much faster
>>>> services)
>>>
>>> Scale for one application is nice (although I'm waiting for your
>>> benchmarks to show that the overhead of calculating URIs dynamically
>>> is crushing, given how cheap CPU time is versus other server side
>>> resources). �How about scale for multiple applications?
>>>
>>> Oh, you only have one? �Good for you! �But that's not a particularly
>>> common problem domain.
>>>
>>>>
>>>>> a JAX-RS based server application, that "care" is expressed by @Path
>>>>
>>>> I am experimenting with that idea.. in order to use regular
>>>> expressions or other DSL facilty to manipulate the final URI
>>>> dinamically.. perhaps storing just the tail of the URI in the databse
>>>> or other format of information that lead me a chance to produce the
>>>> external representation by demand.. this part is my current
>>>> research...... (I prefer the "experimentation" word since I am not a
>>>> formal researcher..)
>>>>
>>>
>>> Please think about the idea that the same business domain resources
>>> may need to be exposed by different applications, using different
>>> resource representations, and different URI schemes, all at the same
>>> time. �Or, even within the same application, exposed in different
>>> pages (web app) or resources (RESTful web service) at the same time.
>>>
>>> Personal history lesson -- when I was first learning web development
>>> (mid-late 1990s), I figured "why not have a toHTML() method on all my
>>> Java business domain model classes"? �It quickly became clear that
>>> different pages within the same app, as well as different apps, needed
>>> different HTML representations of the same business objects. �Indeed,
>>> this realization was one of the motivating factors that led to the
>>> creation of Struts.
>>>
>>> The same is true for RESTful resource representations. �There will be
>>> more than one representation that requires information from a
>>> particular business domain model object, as well as more than one
>>> application (each with their own resource and representation
>>> requirements).
>>>
>>> In MVC terms: �Model classes != View classes.
>>>
>>>>> @Path annotations -- to change the URIs included in your representations.
>>>>
>>>> yes, but you need to iterate over the collections and change manually
>>>> each URI, what can lead you to manipulate thousand of strings before
>>>> to respond to the client.. this part scares me... (think about a
>>>> collection with 100 elements, each with 20 URIs)
>>>
>>> For amusement, you should go grab a raw Atom or RSS feed �from a busy
>>> feed source (I use Google Reader for my feed aggregator, but the same
>>> principle applies to anyone who provides feeds) and see how many URIs
>>> are included. � And, funny thing, none of the apps that *created* that
>>> content had any idea that *I* would be aggregating their feeds, via
>>> Google Reader, for my own use.
>>>
>>> URIs in RESTful web services are a view tier concern, just like CSS style names.
>>>
>>>>
>>>>> In the shopping cart use case (no, I don't care if some people don't like it
>>>>> as an example :-), a well designed REST API should *not* define a URI
>>>>> template like "/checkout" that accepts a POST with a shopping cartURI
>>>>
>>>> That is a basic REST principle .. and it is not related to the way you
>>>> store or calculate the URIs...
>>>>
>>>
>>> Unfortunately, *lots* of theoretically "RESTful API" specifications
>>> include instructions on how to calculate the URI for a particular
>>> operation (versus telling the client "get the URI you need from the
>>> current representation of the resource.). �And I'm as guilty as anyone
>>> else at violating the hypermedia constraint this way, in my earlier
>>> work. �But, my point in this particular scenario was, assuming that
>>> there was a single URI for "checkout", for *all* shopping carts, is
>>> technically feasible, but not a good idea.
>>>
>>>>> concerned, the URI itself is an opaque string.
>>>>
>>>> yes......
>>>>
>>>> thanks for your feedback... interesting.. I will keep thinking about
>>>> your thoughts....
>>>>
>>>>
>>>> �Felipe Ga�cho
>>>>
>>>
>>> Craig
>>>
>>
>>
>>
>> --
>> ------------------------------------------
>> � Felipe Ga�cho
>> � 10+ Java Programmer
>> � CEJUG Senior Advisor
>>
>
>
>
> --
> ------------------------------------------
> � Felipe Ga�cho
> � 10+ Java Programmer
> � CEJUG Senior Advisor
>



-- 
------------------------------------------
   Felipe Ga�cho
   10+ Java Programmer
   CEJUG Senior Advisor

just a question about your domain model sharing:

and what about the code ?

If you code the whole engine logic in a code, and you need a second
application to access the same data, you will need to recode the
engine logic again ?

ok, we all think about "reuse of components", but so far I've seen
ugly hack in the code to simulate the hypermedia engine and that's
what I am trying to do better.. but your points are good.. I will
digest them and try to incorporate the best I can in my design
here.....

2010/2/26 Felipe Ga�cho <fgaucho@...>:
> excellent points.. I will consider that...
>
> 2010/2/26 Craig McClanahan <craigmcc@...>:
>> 2010/2/25 Felipe Ga�cho <fgaucho@...>:
>>>> You're missing a key feature of what both Kevin and I said ... use
>>>> *different* classes for the *resource* domain model and the *business*
>>>> domain model.
>>>
>>> yes, I am aware about that... but the effort to maintain the mapping
>>> between those models generates an extra and unnecessary development
>>> effort ,.... I also noticed some people having a third model when the
>>> data will be rendered in the presentation layer.. (a managedbean or
>>> other component..)... My experiment is looking to reduce the amount of
>>> effort required to synchronize all those models, having only one
>>> model.. and it works fine and the performance is better and
>>> maintenance effort much less than the traditional MVC design...
>>
>> In your business domain objects, do you store the CSS style class that
>> should be used to display this object in a browser? �Of course not:
>>
>> * The *name* of the style class is totally up to the designer.
>>
>> * Do *you* know any designers that care about backwards compatibility
>> of style names? �I don't either ...
>> �but I don't care, as long as the designer updates all the
>> corresponding HTML pages when the style name changes.
>>
>> * Style names can be changed at any time (for example, when you refresh
>> �the look and feel characteristics of your website).
>>
>> * And, of course, there is normally more than one webapp
>> �that needs to be able to render this business domain object,
>> �so having only one style name would not be useful.
>>
>> The same principles apply to designing resource representations -- we
>> should assume that there will be more than one representation that
>> includes this particular object, and more than one RESTful application
>> that needs to provide access to it, so assuming any *single* approach
>> is not likely to help all our users.
>>
>>>
>>>
>>>> Then, each kind of class can have the annotations that are relevant for that tier.
>>>
>>> Usually the classes are identical and you are just including a copy
>>> layer to transfer data between them :)
>>>
>>>> Managing workflow, like obeying the hypermedia constraint, is a view tier concern (from the point of view of a server side developer).
>>>
>>> May be, may be not.. in my case the model contains the sate of the
>>> application, so it is a business concern :)
>>>
>>
>> There is pretty much always more than one application needing your
>> data, so it's more than one business concern :-). �Ideally, you can
>> share the business domain objects across these applications, but the
>> reality is you'll need multiple RESTful resource representations that
>> include data from these business domain objects, for the same reason
>> that you will need multiple HTML representations (even within the same
>> webapp, how many different pages include information from particular
>> domain objects?). �One size does not fit all.
>>
>>>> That's a good thing, because a REST API is typically not the only way that
>>>> such business model objects get manipulated.
>>>
>>> yes, but the effort to manage the hypermedia just in time makes the
>>> whole application much slower.. and it is a repettive task.. that is
>>> one of the reasons that motivated me to push the links in the
>>> database....
>>>
>>>> Self-test time:� are you storing URIs in your database?
>>>
>>> yes. The sate of the application is persistent :) and scales quite
>>> well since I don't need to recalculate the sate on every request..
>>> (ok, memcache can help a bit, but anyway... the hypermedia engine it
>>> is the heavy part of the request - eliminating that I have much faster
>>> services)
>>
>> Scale for one application is nice (although I'm waiting for your
>> benchmarks to show that the overhead of calculating URIs dynamically
>> is crushing, given how cheap CPU time is versus other server side
>> resources). �How about scale for multiple applications?
>>
>> Oh, you only have one? �Good for you! �But that's not a particularly
>> common problem domain.
>>
>>>
>>>> a JAX-RS based server application, that "care" is expressed by @Path
>>>
>>> I am experimenting with that idea.. in order to use regular
>>> expressions or other DSL facilty to manipulate the final URI
>>> dinamically.. perhaps storing just the tail of the URI in the databse
>>> or other format of information that lead me a chance to produce the
>>> external representation by demand.. this part is my current
>>> research...... (I prefer the "experimentation" word since I am not a
>>> formal researcher..)
>>>
>>
>> Please think about the idea that the same business domain resources
>> may need to be exposed by different applications, using different
>> resource representations, and different URI schemes, all at the same
>> time. �Or, even within the same application, exposed in different
>> pages (web app) or resources (RESTful web service) at the same time.
>>
>> Personal history lesson -- when I was first learning web development
>> (mid-late 1990s), I figured "why not have a toHTML() method on all my
>> Java business domain model classes"? �It quickly became clear that
>> different pages within the same app, as well as different apps, needed
>> different HTML representations of the same business objects. �Indeed,
>> this realization was one of the motivating factors that led to the
>> creation of Struts.
>>
>> The same is true for RESTful resource representations. �There will be
>> more than one representation that requires information from a
>> particular business domain model object, as well as more than one
>> application (each with their own resource and representation
>> requirements).
>>
>> In MVC terms: �Model classes != View classes.
>>
>>>> @Path annotations -- to change the URIs included in your representations.
>>>
>>> yes, but you need to iterate over the collections and change manually
>>> each URI, what can lead you to manipulate thousand of strings before
>>> to respond to the client.. this part scares me... (think about a
>>> collection with 100 elements, each with 20 URIs)
>>
>> For amusement, you should go grab a raw Atom or RSS feed �from a busy
>> feed source (I use Google Reader for my feed aggregator, but the same
>> principle applies to anyone who provides feeds) and see how many URIs
>> are included. � And, funny thing, none of the apps that *created* that
>> content had any idea that *I* would be aggregating their feeds, via
>> Google Reader, for my own use.
>>
>> URIs in RESTful web services are a view tier concern, just like CSS style names.
>>
>>>
>>>> In the shopping cart use case (no, I don't care if some people don't like it
>>>> as an example :-), a well designed REST API should *not* define a URI
>>>> template like "/checkout" that accepts a POST with a shopping cartURI
>>>
>>> That is a basic REST principle .. and it is not related to the way you
>>> store or calculate the URIs...
>>>
>>
>> Unfortunately, *lots* of theoretically "RESTful API" specifications
>> include instructions on how to calculate the URI for a particular
>> operation (versus telling the client "get the URI you need from the
>> current representation of the resource.). �And I'm as guilty as anyone
>> else at violating the hypermedia constraint this way, in my earlier
>> work. �But, my point in this particular scenario was, assuming that
>> there was a single URI for "checkout", for *all* shopping carts, is
>> technically feasible, but not a good idea.
>>
>>>> concerned, the URI itself is an opaque string.
>>>
>>> yes......
>>>
>>> thanks for your feedback... interesting.. I will keep thinking about
>>> your thoughts....
>>>
>>>
>>> �Felipe Ga�cho
>>>
>>
>> Craig
>>
>
>
>
> --
> ------------------------------------------
> � Felipe Ga�cho
> � 10+ Java Programmer
> � CEJUG Senior Advisor
>



-- 
------------------------------------------
   Felipe Ga�cho
   10+ Java Programmer
   CEJUG Senior Advisor

2010/2/25 Felipe Ga�cho <fgaucho@...>:
>> You're missing a key feature of what both Kevin and I said ... use
>> *different* classes for the *resource* domain model and the *business*
>> domain model.
>
> yes, I am aware about that... but the effort to maintain the mapping
> between those models generates an extra and unnecessary development
> effort ,.... I also noticed some people having a third model when the
> data will be rendered in the presentation layer.. (a managedbean or
> other component..)... My experiment is looking to reduce the amount of
> effort required to synchronize all those models, having only one
> model.. and it works fine and the performance is better and
> maintenance effort much less than the traditional MVC design...

In your business domain objects, do you store the CSS style class that
should be used to display this object in a browser?  Of course not:

* The *name* of the style class is totally up to the designer.

* Do *you* know any designers that care about backwards compatibility
of style names?  I don't either ...
  but I don't care, as long as the designer updates all the
corresponding HTML pages when the style name changes.

* Style names can be changed at any time (for example, when you refresh
  the look and feel characteristics of your website).

* And, of course, there is normally more than one webapp
  that needs to be able to render this business domain object,
  so having only one style name would not be useful.

The same principles apply to designing resource representations -- we
should assume that there will be more than one representation that
includes this particular object, and more than one RESTful application
that needs to provide access to it, so assuming any *single* approach
is not likely to help all our users.

>
>
>> Then, each kind of class can have the annotations that are relevant for that tier.
>
> Usually the classes are identical and you are just including a copy
> layer to transfer data between them :)
>
>> Managing workflow, like obeying the hypermedia constraint, is a view tier concern (from the point of view of a server side developer).
>
> May be, may be not.. in my case the model contains the sate of the
> application, so it is a business concern :)
>

There is pretty much always more than one application needing your
data, so it's more than one business concern :-).  Ideally, you can
share the business domain objects across these applications, but the
reality is you'll need multiple RESTful resource representations that
include data from these business domain objects, for the same reason
that you will need multiple HTML representations (even within the same
webapp, how many different pages include information from particular
domain objects?).  One size does not fit all.

>> That's a good thing, because a REST API is typically not the only way that
>> such business model objects get manipulated.
>
> yes, but the effort to manage the hypermedia just in time makes the
> whole application much slower.. and it is a repettive task.. that is
> one of the reasons that motivated me to push the links in the
> database....
>
>> Self-test time:� are you storing URIs in your database?
>
> yes. The sate of the application is persistent :) and scales quite
> well since I don't need to recalculate the sate on every request..
> (ok, memcache can help a bit, but anyway... the hypermedia engine it
> is the heavy part of the request - eliminating that I have much faster
> services)

Scale for one application is nice (although I'm waiting for your
benchmarks to show that the overhead of calculating URIs dynamically
is crushing, given how cheap CPU time is versus other server side
resources).  How about scale for multiple applications?

Oh, you only have one?  Good for you!  But that's not a particularly
common problem domain.

>
>> a JAX-RS based server application, that "care" is expressed by @Path
>
> I am experimenting with that idea.. in order to use regular
> expressions or other DSL facilty to manipulate the final URI
> dinamically.. perhaps storing just the tail of the URI in the databse
> or other format of information that lead me a chance to produce the
> external representation by demand.. this part is my current
> research...... (I prefer the "experimentation" word since I am not a
> formal researcher..)
>

Please think about the idea that the same business domain resources
may need to be exposed by different applications, using different
resource representations, and different URI schemes, all at the same
time.  Or, even within the same application, exposed in different
pages (web app) or resources (RESTful web service) at the same time.

Personal history lesson -- when I was first learning web development
(mid-late 1990s), I figured "why not have a toHTML() method on all my
Java business domain model classes"?  It quickly became clear that
different pages within the same app, as well as different apps, needed
different HTML representations of the same business objects.  Indeed,
this realization was one of the motivating factors that led to the
creation of Struts.

The same is true for RESTful resource representations.  There will be
more than one representation that requires information from a
particular business domain model object, as well as more than one
application (each with their own resource and representation
requirements).

In MVC terms:  Model classes != View classes.

>> @Path annotations -- to change the URIs included in your representations.
>
> yes, but you need to iterate over the collections and change manually
> each URI, what can lead you to manipulate thousand of strings before
> to respond to the client.. this part scares me... (think about a
> collection with 100 elements, each with 20 URIs)

For amusement, you should go grab a raw Atom or RSS feed  from a busy
feed source (I use Google Reader for my feed aggregator, but the same
principle applies to anyone who provides feeds) and see how many URIs
are included.   And, funny thing, none of the apps that *created* that
content had any idea that *I* would be aggregating their feeds, via
Google Reader, for my own use.

URIs in RESTful web services are a view tier concern, just like CSS style names.

>
>> In the shopping cart use case (no, I don't care if some people don't like it
>> as an example :-), a well designed REST API should *not* define a URI
>> template like "/checkout" that accepts a POST with a shopping cartURI
>
> That is a basic REST principle .. and it is not related to the way you
> store or calculate the URIs...
>

Unfortunately, *lots* of theoretically "RESTful API" specifications
include instructions on how to calculate the URI for a particular
operation (versus telling the client "get the URI you need from the
current representation of the resource.).  And I'm as guilty as anyone
else at violating the hypermedia constraint this way, in my earlier
work.  But, my point in this particular scenario was, assuming that
there was a single URI for "checkout", for *all* shopping carts, is
technically feasible, but not a good idea.

>> concerned, the URI itself is an opaque string.
>
> yes......
>
> thanks for your feedback... interesting.. I will keep thinking about
> your thoughts....
>
>
> �Felipe Ga�cho
>

Craig

Hi,

as an update to yesterday's API classification I've added an impact analysis that shows the effect of the violation of the various constraints is on the overall system properties.

> <http://nordsc.com/ext/classification_of_http_based_apis.html>

Jan


-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

> > I think we must differentiate here between CRUD GUIs (which I
> dislike) and CRUD APIs:
> > As SQL works so well, I don't actually see a real need to invent more
> commands. I mean,
> > what benefit should it actually bringt?
> 
> You gain a API that has better granularity than simply CRUD. Yes,
> inevitably, you end up doing pure "atomic" CRUD against, say, a SQL
> database. But there's no reason you should be forced to exposed that
> limited of an API to your clients. You should be able to have higher
> level interactions with your sever than just raw CRUD, actions that
> themselves may manifest into sever primitive hits against your data
> store.
> 
> The point of the Common Interface isn't so much to hamstring
> applications in to a pure CRUD HTTP view of the world, but rather to
> help ensure you don't simply run off hog wild creating eleventy
> zillion new verbs. Taking a constrained, conservative view at the verb
> layer and how they're used can make the API easier to use, and more
> approachable, rather than a wiener dog nest of exceptions and special
> cases and what ifs. Consistent application of a consistent, common
> interface.
> 
> But that doesn't mean you're limited solely to CRUD.

While our application is highly complex and in pre-REST times was using lots
of very special RPC methods, I do actually not feel "constrained" by CRUD,
also CRUD does not mean that you must have a 1:1 mapping of each request to
exactly one  database penetration.

Example:

Our software allow to create "inspection orders" from "inspection order
templates". Such a template or instance contains lots of very deep children
and thousands of data fields. While one is free to do nearly anything in a
template, if you want to make an instance from a template, you have to pass
a very complex validation which includes hundreds of rules on a lot of the
fields in all of the child object. It is one of the most complex algorithms
I've ever seen with thousands of LoC. It includes such a lot of database
requests that it must work completely on the server to be fast enough.

In RPC times, this was done as one bug stored procedure, reading lots of
rows, and writing lots of rows. All the caller had to do was "CALL
CreateInspectionFromTemplate(ID)". What a simple API.

Now we turn it to REST. The server is unchanged: It still calls the same
SQL. We just added a RESTful layer ontop of it. To execute the (nearly) same
procedure, you now will just do:

GET /templates/{id}
POST /orders/

This triggers the stored procedure, runs all the thousands of lines of code,
and creates the object on the database. What you'll get back is an URI of
the from /order/{id} for the newly created instance (the root of the tree of
rows created in the database forming the instance created from the
template), and a validation result (XML, either beeing empty, or containing
a lot of validation faults).

So CRUD does not mean to create exactly one row, or to not being able to
execute highly complex transactions. As you can see, I can execute a complex
algorithm running on thousands of database rows, creating even more
thousands, and thus performance a very complex business task, with a simple
CRUD operation, without the need for "RPC-like" names or URIs.

THAT's why I said, why not doing CRUD? :-)

Regards
Markus

Kevin,

 

as with anything in REST, the answer is like always: How would the solution
look like if your client would be a browser? ;-)

 

In fact, I still do not understand your issue: Just like your browser
doesn't know what it would receive at the end of a <A> link that you
clicked, your REST client does not need to know the type prior to invoking
the http method, and it will see the actually received content type as soon
as it received the content. Just as a browser sees the content of a
referenced resource after following an <A> link in a HTML file. I don't see
why you need to know the type *before* receiving it. At time of requesting,
the client shall just provide a list of what types *it can process* and of
it's preference. You browser always send "I like HTML most", independent of
what the server actually can send.

 

Also, why do you like to use different types at all? Why not just
restricting your service to work with XML and / or JSON always instead of
switching types all the time (I just don't see the use of this, while
certainly it is a valid business requirement).

 

Regards

Markus

 

From: Kevin Duffey [mailto:andjarnic@...] 
Sent: Mittwoch, 24. Februar 2010 21:59
To: rest-discuss@yahoogroups.com; Markus KARG
Subject: RE: [rest-discuss] Re: [Jersey] Moved thread to rest-discuss /
HATEOAS-via-HTTP: Which HTTP Method to use to follow link?

 


Markus,

What I meant was... what does the response look like? Is it something like:

<links>
   <link rel="create" uri="...." method="post" media-type="application/xml,
application/json"/>
  <link rel="self" uir="..." method="get, put"
media-type="application/xml"/>
</links>

That is.. if I do some sort of GET or OPTION or what have you on a published
URI, and two URIs come back indicating I can get the self and post a create
to another URI, given that we can specify different media types on each
method (at least in Jersey), I am curious what lets the client side no WHAT
to set the header Content-Type to, in order to get it to the right method on
the server side for handling?

With JAX-RS, we can specify two methods from above:

@POST
@Consumes({"application/xml", "application/json"})
public Response create(...){}

@PUT
@Consumes({"application/xml"})
public Response update(...){}

@GET
@Produces({"application/xml"})
public Response get(...){}


I am curious as I try to build out a HATEOAS based response system, how I
send back multiple links that can be called by the client at that point, and
how I tell the client the specific media type each URI can handle? Or is
that in a document instead that says "for this URI, you must use the media
type..."?



--- On Wed, 2/24/10, Markus KARG <markus@...> wrote:


From: Markus KARG <markus@...>
Subject: RE: [rest-discuss] Re: [Jersey] Moved thread to rest-discuss /
HATEOAS-via-HTTP: Which HTTP Method to use to follow link?
To: "'Kevin Duffey'" <andjarnic@...>, rest-discuss@yahoogroups.com
Date: Wednesday, February 24, 2010, 10:19 AM

If we stick to http in the original definition's sense, you don't need to
define the mime type at all: The client will supply a list of accepted media
type preferences in a request, and will get one of those back. The actual
returned type is found in the header. If you want ONLY the header, don't use
GET but HEAD. Rather simple, isn't it?

 

From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com] On
Behalf Of Kevin Duffey
Sent: Dienstag, 23. Februar 2010 21:34
To: rest-discuss@yahoogroups.com
Subject: Re: [rest-discuss] Re: [Jersey] Moved thread to rest-discuss /
HATEOAS-via-HTTP: Which HTTP Method to use to follow link?

 






Can one of you guys/gals explain to me how you determine the media type for
each URI returned? This is the one thing that still perplexes me. In your
example, you return the name, rel, and URI. But from those three items, how
do I set the media type for Content-Type when I want to make a request?

On the server side, I might support different media types for each of my
methods, some how I would assume I need to return that info as well so that
a developer can set the right media type for the request.

Or perhaps I've completely confused the importance and use of media types
with regards to HATEOAS responses that provide potentially multiple links
for the activities that can be performed for a given state?

Thank you.



--- On Tue, 2/23/10, Kris Zyp <kris@...> wrote:


From: Kris Zyp <kris@...>
Subject: Re: [rest-discuss] Re: [Jersey] Moved thread to rest-discuss /
HATEOAS-via-HTTP: Which HTTP Method to use to follow link?
To: "Markus KARG" <markus@...>
Cc: "'Jan Algermissen'" <algermissen1971@...>, "'REST Discuss'"
<rest-discuss@yahoogroups.com>
Date: Tuesday, February 23, 2010, 11:31 AM

  

-----BEGIN PGP SIGNED MESSAGE----- 
Hash: SHA1 
 


On 2/23/2010 11:58 AM, Markus KARG wrote:
> this is interesting! As I am
working with XSL / XML a lot, I did

> not take such a deep look at JSON. Is that type of link support

> native to JSON or is that just a specific use of JSON?

It is not "native" to application/ json, it is part of JSON Schema
(application/ schema+json) [1], and is therefore a meta-description of
the links that can understood from the data/documents.

[1]  <http://tools.ietf.org/html/draft-zyp-json-schema> http://tools.
ietf.org/ html/draft- zyp-json- schema

> I wonder whether the outline
type of link description is actually
RESTful:
> I mean, "create order" clearly
is a command, and such is not

> document driven but method driven, which in turn looks like RPC
to

> me?

"create_order" was just what I used to make it clear, since I thought
you were asking for a way to indicate to a client how to navigate
to/submit a request to create an order (using a POST).

- -- 
Kris Zyp
SitePen
(503) 806-1841
 <http://sitepen.com> http://sitepen. com
-----BEGIN PGP SIGNATURE--- -- 
Version: GnuPG v1.4.9 (MingW32) 
Comment: Using GnuPG with Mozilla -  <http://enigmail.mozdev.org/>
http://enigmail. mozdev.org/ 
 
iEYEARECAAYFAkuELQs ACgkQ9VpNnHc4zAx +/ACgl79LdqrDrkU II9Uz2tSXJkiz 
EqcAn0Lx28cSF8A6A5S +il74gAE24ye7 
=SW2g 
-----END PGP SIGNATURE--- -- 








 

Good work, but actually one thing needs to be added: REST has nothing to do
with http. It is an architectural style. Certainly most REST applications
are using http currently. But for correctness, the table should not say
"REST" but "REST over http". ;-)

> -----Original Message-----
> From: rest-discuss@yahoogroups.com [mailto:rest-
> discuss@yahoogroups.com] On Behalf Of Jan Algermissen
> Sent: Donnerstag, 25. Februar 2010 14:19
> To: REST Discuss
> Subject: [rest-discuss] Differentiating HTTP-based APIs
> 
> Hi,
> 
> I have put together a table classifying HTTP-based API-types according
> to the REST constraints they adhere to:
> 
> <http://nordsc.com/ext/classification_of_http_based_apis.html>
> 
> Hope this is useful.
> 
> Jan
> 
> -----------------------------------
>  Jan Algermissen, Consultant
>  NORD Software Consulting
> 
>  Mail: algermissen@...
>  Blog: http://www.nordsc.com/blog/
>  Work: http://www.nordsc.com/
> -----------------------------------
> 
> 
> 
> 
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

On Feb 26, 2010, at 9:13 PM, Markus KARG wrote:

> Good work, but actually one thing needs to be added: REST has nothing to do
> with http. It is an architectural style. Certainly most REST applications
> are using http currently. But for correctness, the table should not say
> "REST" but "REST over http". ;-)

Yep, that's correct. I am mixing levels there.

OTH, read the others as names for 'styles' (e.g. 'RPC Resource Identifier Tunneling' as opposed to 'RPC URI-Tunneling'. Then the levels fit again :-)

Jan

> 
>> -----Original Message-----
>> From: rest-discuss@yahoogroups.com [mailto:rest-
>> discuss@yahoogroups.com] On Behalf Of Jan Algermissen
>> Sent: Donnerstag, 25. Februar 2010 14:19
>> To: REST Discuss
>> Subject: [rest-discuss] Differentiating HTTP-based APIs
>> 
>> Hi,
>> 
>> I have put together a table classifying HTTP-based API-types according
>> to the REST constraints they adhere to:
>> 
>> <http://nordsc.com/ext/classification_of_http_based_apis.html>
>> 
>> Hope this is useful.
>> 
>> Jan
>> 
>> -----------------------------------
>> Jan Algermissen, Consultant
>> NORD Software Consulting
>> 
>> Mail: algermissen@...
>> Blog: http://www.nordsc.com/blog/
>> Work: http://www.nordsc.com/
>> -----------------------------------
>> 
>> 
>> 
>> 
>> 
>> 
>> ------------------------------------
>> 
>> Yahoo! Groups Links
>> 
>> 
>> 
> 
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

> > I think we must differentiate here between CRUD GUIs (which I
> dislike) and CRUD APIs: As SQL works so well, I don't actually see a
> real need to invent more commands. I mean, what benefit should it
> actually bringt? If I want my server to send an email, what would be
> wrong to say that I must do a POST to the "http://.../mail-outbox/"
> URI, which in turn will make the server send away the received entity
> as an email, and which ist a RESTful operation
> 
> Nothing is wrong with that. That is how domain specific operations
> ('goals' if you want) are achieved: tell a resource *with the
> appropriate semantics* to process-this (POST). So, if you learned from
> some hypermedia that http://.../mail-outbox/ has the semantics of
> sending a mail when you POST something to it then that is how you
> achieve that domain goal.
> 
> The need for the hypermedia is there because that is how the client
> learns ar runtime that http://.../mail-outbox/ has these semantics.
> 

I need to disagree here: The WWW is working without anybody having to learn
about the semantics of a particular method called upon a particular URI.
Why? Because it is defined by http iteself! I think it is just a wrong idea
to impose any other semantics than those defined by http.

Example:

A POST on an URI implies that a new resource is created (just like an INSERT
defines that in SQL).

The fact that the created object actually is an email but not a row in a
database or a file on disk plays no role. The semantics are the same. So
there actually is nothing to learn. It is just clear that if you want to
send an email, that it obviously must be POST, since a PUT would imply an
update of an existing object (just like UPDATE defines that in SQL) - but
you cannot update an email, as it certainly is already sent!

Just keep things simple and drill down to the bottom, and you'll see that
there is no need for "learning" about semantics.

More complex example:

You like to instruct your car to drive either left or right etc.: You know
your car reacts if you send "application/instruction+xml" as that might be
the mime found on Wikipedia for car steering systems (containing primitives
like "left turn", "right turn", etc. or complex instructions like "drive to
los angeles") to the URI "http://mycar/steering/" (as this might be printed
on your car's key). What would PUT / POST / DELETE / GET do? Is there a need
to defined the actual semantics (I suppose: No). While driving a car
actually is such complex that there still (sigh!) is no automatic driving
car to buy even in 2010, the answer to this question is rather simple:

POST ("INSERT"): Uploads a new instruction, so obviously the car will finish
the existing instructions and after that follow the new one. It doesn't
matter that the result might not be cached, as it will as you will GET it
later using the new instruction's server-generated URI returned by POST. The
uploaded instruction is kept in some form of a queue, as you didn't say PUT
to replace it. It's just obvious, just as a human driver also would
understand a sequence of instructions as a queue.

DELETE (on sub-resource) ("DELETE"): Deletes the specified instruction, i.
e. will stop executing it at once if already running, otherwise just drops
it from the queue of queued instructions.

GET (on root) ("SELECT"): Returns a list of all uploaded instructions ("What
will the car do in sequence?")

GET (on sub-resource) ("SELECT"): Returns the specified instruction,
possibly to learn about it's execution status ("Did the car already follow
this instruction, or is it still in the queue?")

PUT (on sub-resource) ("UPDATE"): Overwrites the specified instruction by
this new one, i. e. will stop executing it and instead execute the new one
when already running (otherwise just replaces it in the queue). Just as a
human driver would understand if you say: "I said turn left next, but I
actually meant turn right!".

Even in this complex example, the semantics of PUT / POST / DELETE / GET is
really obvious and follows exacty the WWW semantics. No need to define
semantics. Just expect anything on earth to be a document that can be
created, read, updated, deleted. Nobody says that CRUD must deal with
databases or single rows in a table. The CRUD's "C" or "U" can be
implemented as highly complex algorithms, as the car example shows.

So I just wait for a business use case (not a synthetic example) that will
not be that simple in the end. ;-)


> Note: if the general semantics of the domain operation map to PUT or
> DELETE or PATCH these specific methods should be used because you get
> more visibility compared to POST (which has visibility zero). For
> example, a PUT on /orders/2 allows caches to flush what they have for
> /orders/2 and store the response to the PUT. If you POST /orders/2 the
> caches just flush - and they only do this not because they know what is
> going on but because that is the (necessary) default behavior for POST.

In this particular example, actually I do not see any problem in the fact
that a cache is flushing as the target was to create an email: There is no
result to flush actually. ;-) But I understand what you mean actually.

Hey Markus...

I think we're missing each other on this conversation. First, like you say, a browser would understand ahead of time what an <A> element is and what to do with it. As a client consuming my service API they *should* know that what ever way I return the various links that they can make use of at some given state, they will know what to do. I believe this is what you are saying. However, being that my service can evolve.. I can add new URI links for say, new features later on, there has to be a way to describe each link's method to use (get/post/put/delete) correct? I mean, I can't just return something like:

<links>
� <link href="http://myservice.com/create"/>
� <link href="http://myservice.com/orders"/>
� <link href="http://myservice.com/history"/>
</links>

and expect a client to know that they can post to the /create, get from /orders and get a /history/{id} can I? If instead I returned:

<links>

� <link href="http://myservice.com/create" method="post"/>

� <link href="http://myservice.com/orders" method="get"/>

� <link href="http://myservice.com/history" method="get,put,delete"/>

</links>


Is that wrong? That would allow a client, as well as a bot to be able to determine what it can do with each resource link.

Furthermore, I thought the use of media types was important? I am still a bit rusty with this, hence my questions, but I thought there was some push to use media types like "application/vnd.com.myservice.create+xml" for the /create resource and that that would be set as the Content-Type on the request... in Jersey, I'd have a method like this set up:

@POST
@Consumes("application/vnd.com.myservice.create+xml")
public Response create(..){
}

But, in order for a client to know WHAT media type to set the Content-Type to when sending the request, I'd have to return that media type string in my links:

<links>


� <link href="http://myservice.com/create" method="post" type="application/vnd.com.myservice.create+xml"/>


</links>



So that a client, be it a developer consuming my API or a bot scanning the response, could look at each <link> element, and know that it can post/put/delete/get and what to set the Content-Type header to so that it goes to the right method. Naturally the client doesn't know that it will go to the right method, the point here is that the media type is specific for each resource. 

So my question is really.. the type="..." portion.. is that what would or should be done.. passed back as part of a response so that client consumers can figure out what method(s), URI and media type to set when making a request? I do NOT mean to say that a client should know BEFORE that this is what is coming back. Simply that WHEN it comes back, what attributes to look for in order to make the next request.

If that does not explain it well enough, I don't know what else to say. 




      

Hi Felipe,

So, it seems you are really having a hard time with this issue of reducing how much code it takes to do what you would like.  As Craig said, you're allowing your "view" tier mix in with your "model" tier. Neither should know about the other. There is a reason, in my opinion, MVC has stuck around so long and is so well known and implemented. To break this well sought after development paradigm in order to reduce some code to me is going backwards.

Now, there are some things you could do that could keep the concerns separated, but at the same time reduce code... but usually getting something for free means giving something up. I'll fill you in on something I've done recently that works, although I have not tested it, I imagine I may be giving up a little performance for a lot of convenience. In the end, there are things I can do to increase performance... but if I mix my model with my view tiers, and some other business need comes up that requires a different view with the same model.. I am going to have to write a lot of new code or spend a lot of time rewriting it the way it should be, which is separated.

So, what I did was to use XSD with JAXB for my "view" model that allows me to automatically thanks to the wonders of JAXB and Jersey's ability to convert incoming xml/json requests into objects, and vice versa, send xml/json in response from my XSD objects. Now, as you say, and I too have done, my XSD/JAXB classes have pretty much identical method names and properties. For example, my user entity is basically a name, street, city, state zip, area, country, phone and email. Likewise, my XSD mimics those fields, and in my case they are basically identical. Enough so that the generated XSD/JAXB object properties match with the entity bean property names.

What I decided to do was in my ejb session beans, which are stateless using the @Stateless, to pass in the JAXB model object as a paramter to the method that would utilize the same entity bean on the back end. I also utilized the apache BeanUtils class to copy properties for me. This is where it might cause a slight performance hiccup..I am not entirely sure how the copy method does what it does, but I am guessing with reflection. Still, reflection is much faster now, so I am far less worried about a fraction more time lost given the benefits I get of the separation and cleaner code. And meanwhile, as you can see, it's not that much code. This particular implementation works with all objects, so I can quickly copy/paste this method for whatever my needs are. I am not having to call tons of user.setXxx(u.getXxx()) methods in code.

@Stateless
public class UserEJBSession{
  @PersistenceContext(unitName = "myPersistenceUnit")
  EntityManager em;

  public long createUser(com.myjaxbgeneratedpackage.models.User user) {
    User u = new User();

    try {
        BeanUtils.copyProperties(u, user);
    } catch (InvocationTargetException ite) {
        ite.printStackTrace(System.out);
    } catch (IllegalAccessException e) {
        e.printStackTrace(System.out);
    }

    em.persist(u);
    em.flush();
    em.refresh(u);
    return u.getId().longValue();
  }



The above, to me, is not much code, it works, and it allows me to keep my domains and views separated. It allows me to make use of my domains for other purposes. I generally put my JAXB/XSD into a separate project, build it and put the .jar into this projects /lib directory. Thus, it is perfectly fine for my ejb session to "see" the JAXB model classes. I am NOT allowing my entity classes to use the JAXB objects. The session bean also does not dictate the "view" going back. The resource class (which would call this createUser method passing in to it the JAXB user object that it created when the request came in with the xml or json of a user) gets back the response from this method and then figures out what to respond with. If this were a web site, it would forward to some JSP page, perhaps setting some request scoped properties that the JSP page could use for it's response. As my service is a rest service, it would return a response with probably a 201
 created and a URI linking to the new created resource. The point being, the service does not see or know about the back end entity model, and the back end entity model knows nothing of the view or the JAXB classes.

Another thing to think about. Part of JEE6 is this new profile setup, where by you can install a subset of the JEE6 spec as part of the container. For example, I think the Web Profile provides the servlet/jsp, some ejb but not all of it, no JMS, etc. I don't know for sure, but it may be that if you were to try to deploy your app with your mixed models as you have them now, they may not deploy into this Web Profile container. Don't quote me on this, but it is something to think about.

Another thing to consider is scalability. Given that the ejb/entity stuff is going to be working with the database, it's likely that it will require more time to work with back end resources. As such, you may need to scale the server farm (for larger sites) more so in that tier than say, the front end rest/jsp/servlet view tier. If you deploy everything completely mixed up, that is fine, but often times many of the front end requests can be handled via cache, or non-back end needs and responded to quickly. By separating it, you could provide fewer servers to handle the majority of front end requests, while scaling up the back end as needed.

HTH



just a question about your domain model sharing:



and what about the code ?



If you code the whole engine logic in a code, and you need a second

application to access the same data, you will need to recode the

engine logic again ?



ok, we all think about "reuse of components", but so far I've seen

ugly hack in the code to simulate the hypermedia engine and that's

what I am trying to do better.. but your points are good.. I will

digest them and try to incorporate the best I can in my design

here.....



2010/2/26 Felipe Gaúcho <fgaucho@gmail. com>:

> excellent points.. I will consider that...

>

> 2010/2/26 Craig McClanahan <craigmcc@gmail. com>:

>> 2010/2/25 Felipe Gaúcho <fgaucho@gmail. com>:

>>>> You're missing a key feature of what both Kevin and I said ... use

>>>> *different* classes for the *resource* domain model and the *business*

>>>> domain model.

>>>

>>> yes, I am aware about that... but the effort to maintain the mapping

>>> between those models generates an extra and unnecessary development

>>> effort ,.... I also noticed some people having a third model when the

>>> data will be rendered in the presentation layer.. (a managedbean or

>>> other component..) ... My experiment is looking to reduce the amount of

>>> effort required to synchronize all those models, having only one

>>> model.. and it works fine and the performance is better and

>>> maintenance effort much less than the traditional MVC design...

>>

>> In your business domain objects, do you store the CSS style class that

>> should be used to display this object in a browser?  Of course not:

>>

>> * The *name* of the style class is totally up to the designer.

>>

>> * Do *you* know any designers that care about backwards compatibility

>> of style names?  I don't either ...

>>  but I don't care, as long as the designer updates all the

>> corresponding HTML pages when the style name changes.

>>

>> * Style names can be changed at any time (for example, when you refresh

>>  the look and feel characteristics of your website).

>>

>> * And, of course, there is normally more than one webapp

>>  that needs to be able to render this business domain object,

>>  so having only one style name would not be useful.

>>

>> The same principles apply to designing resource representations -- we

>> should assume that there will be more than one representation that

>> includes this particular object, and more than one RESTful application

>> that needs to provide access to it, so assuming any *single* approach

>> is not likely to help all our users.

>>

>>>

>>>

>>>> Then, each kind of class can have the annotations that are relevant for that tier.

>>>

>>> Usually the classes are identical and you are just including a copy

>>> layer to transfer data between them :)

>>>

>>>> Managing workflow, like obeying the hypermedia constraint, is a view tier concern (from the point of view of a server side developer).

>>>

>>> May be, may be not.. in my case the model contains the sate of the

>>> application, so it is a business concern :)

>>>

>>

>> There is pretty much always more than one application needing your

>> data, so it's more than one business concern :-).  Ideally, you can

>> share the business domain objects across these applications, but the

>> reality is you'll need multiple RESTful resource representations that

>> include data from these business domain objects, for the same reason

>> that you will need multiple HTML representations (even within the same

>> webapp, how many different pages include information from particular

>> domain objects?).  One size does not fit all.

>>

>>>> That's a good thing, because a REST API is typically not the only way that

>>>> such business model objects get manipulated.

>>>

>>> yes, but the effort to manage the hypermedia just in time makes the

>>> whole application much slower.. and it is a repettive task.. that is

>>> one of the reasons that motivated me to push the links in the

>>> database....

>>>

>>>> Self-test time:  are you storing URIs in your database?

>>>

>>> yes. The sate of the application is persistent :) and scales quite

>>> well since I don't need to recalculate the sate on every request..

>>> (ok, memcache can help a bit, but anyway... the hypermedia engine it

>>> is the heavy part of the request - eliminating that I have much faster

>>> services)

>>

>> Scale for one application is nice (although I'm waiting for your

>> benchmarks to show that the overhead of calculating URIs dynamically

>> is crushing, given how cheap CPU time is versus other server side

>> resources).  How about scale for multiple applications?

>>

>> Oh, you only have one?  Good for you!  But that's not a particularly

>> common problem domain.

>>

>>>

>>>> a JAX-RS based server application, that "care" is expressed by @Path

>>>

>>> I am experimenting with that idea.. in order to use regular

>>> expressions or other DSL facilty to manipulate the final URI

>>> dinamically. . perhaps storing just the tail of the URI in the databse

>>> or other format of information that lead me a chance to produce the

>>> external representation by demand.. this part is my current

>>> research.... .. (I prefer the "experimentation" word since I am not a

>>> formal researcher.. )

>>>

>>

>> Please think about the idea that the same business domain resources

>> may need to be exposed by different applications, using different

>> resource representations, and different URI schemes, all at the same

>> time.  Or, even within the same application, exposed in different

>> pages (web app) or resources (RESTful web service) at the same time.

>>

>> Personal history lesson -- when I was first learning web development

>> (mid-late 1990s), I figured "why not have a toHTML() method on all my

>> Java business domain model classes"?  It quickly became clear that

>> different pages within the same app, as well as different apps, needed

>> different HTML representations of the same business objects.  Indeed,

>> this realization was one of the motivating factors that led to the

>> creation of Struts.

>>

>> The same is true for RESTful resource representations.  There will be

>> more than one representation that requires information from a

>> particular business domain model object, as well as more than one

>> application (each with their own resource and representation

>> requirements) .

>>

>> In MVC terms:  Model classes != View classes.

>>

>>>> @Path annotations -- to change the URIs included in your representations.

>>>

>>> yes, but you need to iterate over the collections and change manually

>>> each URI, what can lead you to manipulate thousand of strings before

>>> to respond to the client.. this part scares me... (think about a

>>> collection with 100 elements, each with 20 URIs)

>>

>> For amusement, you should go grab a raw Atom or RSS feed  from a busy

>> feed source (I use Google Reader for my feed aggregator, but the same

>> principle applies to anyone who provides feeds) and see how many URIs

>> are included.   And, funny thing, none of the apps that *created* that

>> content had any idea that *I* would be aggregating their feeds, via

>> Google Reader, for my own use.

>>

>> URIs in RESTful web services are a view tier concern, just like CSS style names.

>>

>>>

>>>> In the shopping cart use case (no, I don't care if some people don't like it

>>>> as an example :-), a well designed REST API should *not* define a URI

>>>> template like "/checkout" that accepts a POST with a shopping cartURI

>>>

>>> That is a basic REST principle .. and it is not related to the way you

>>> store or calculate the URIs...

>>>

>>

>> Unfortunately, *lots* of theoretically "RESTful API" specifications

>> include instructions on how to calculate the URI for a particular

>> operation (versus telling the client "get the URI you need from the

>> current representation of the resource.).  And I'm as guilty as anyone

>> else at violating the hypermedia constraint this way, in my earlier

>> work.  But, my point in this particular scenario was, assuming that

>> there was a single URI for "checkout", for *all* shopping carts, is

>> technically feasible, but not a good idea.

>>

>>>> concerned, the URI itself is an opaque string.

>>>

>>> yes......

>>>

>>> thanks for your feedback... interesting. . I will keep thinking about

>>> your thoughts....

>>>

>>>

>>>  Felipe Gaúcho

>>>

>>

>> Craig

>>

>

>

>

> --

> ------------ --------- --------- --------- ---

>   Felipe Gaúcho

>   10+ Java Programmer

>   CEJUG Senior Advisor

>



-- 

------------ --------- --------- --------- ---

   Felipe Gaúcho

   10+ Java Programmer

   CEJUG Senior Advisor



    
     

    
    


 



  






      

Kevin,

 

if I were you, I would not do this:


<links>
  <link href="http://myservice.com/create"/>
  <link href="http://myservice.com/orders"/>
  <link href="http://myservice.com/history"/>
</links>

 

as "create" is a command verb, not a resource name.

 

If you instead think of documents solely, then you should be able to create
things by a POST of a document in the right folder. For example, if you like
to order something, you don't do a PUT in create but a POST in orders. As
the meaning of http methods is semantically clear, there wouldn't be a need
to declare what a method is good for. The need to define what a method
semantically means arises solely due to two reasons: Missing thinking in
documents and using command verbs. As soon as you start modelling your
application in terms of documents, you will notice that it is clear what a
http method will do.

 

It seems you have misunderstood a bit what the media type header is good for
when invoking a http method. It tells the receiving party not which method
to select on the server side (this is just a technical side effect), but it
tells the receiving party what the the type of the actually uploaded
document is. So there is no need to know what the server can process, but
instead there is a need for the server to understand the mime types that
your client like to send (see that this is a different approach?).

 

Typically, a HTML server ("Web Server") will be able to process HTML. It
won't make much sense to have an API that says "This web server supports
HTML only at GET, while at PUT it wants to receive a PDF instead.". Same is
with business applications. If you are developing a web shop, then it makes
sense that the *complete* shop is able to deal with
"application/product+xml" for example. It makes no sense to have different
MIME type for each method. If the server doesn't accept a particular mime
type at one particular URI, it can just reject it (this is part of http
already). You don't need to know it earlier. I mean, what shall it be good
for to know? If you client would know and is able to serve it, it could have
served it without knowing it, just by trial. If the client would know and is
NOT able to serve it, it won't be any better off. So what have you won?
Nothing! As in REST the driver is always the client, the client can just do
what it wants to do, and the server must be able to do that or reject the
request. This is how the web works, and I don't see why it should be changed
for REST.

 

It seems you like to give the server control on what the client has to do.
This is wrong. In REST, still (as in every C/S architecture), it is the
client that tells the server what to do. The server can just give advice
what it thinks would be useful (like presenting some links), and it can
support some MIME types while it does not support others. But the boss is
the client. The server can only serve it, or reject it.

 

Regards

Markus

 

 

From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com] On
Behalf Of Kevin Duffey
Sent: Samstag, 27. Februar 2010 07:00
To: rest-discuss@yahoogroups.com
Subject: RE: [rest-discuss] Re: [Jersey] Moved thread to rest-discuss /
HATEOAS-via-HTTP: Which HTTP Method to use to follow link?

 







Hey Markus...

I think we're missing each other on this conversation. First, like you say,
a browser would understand ahead of time what an <A> element is and what to
do with it. As a client consuming my service API they *should* know that
what ever way I return the various links that they can make use of at some
given state, they will know what to do. I believe this is what you are
saying. However, being that my service can evolve.. I can add new URI links
for say, new features later on, there has to be a way to describe each
link's method to use (get/post/put/delete) correct? I mean, I can't just
return something like:

<links>
  <link href="http://myservice.com/create"/>
  <link href="http://myservice.com/orders"/>
  <link href="http://myservice.com/history"/>
</links>

and expect a client to know that they can post to the /create, get from
/orders and get a /history/{id} can I? If instead I returned:

<links>
  <link href="http://myservice.com/create" method="post"/>
  <link href="http://myservice.com/orders" method="get"/>
  <link href="http://myservice.com/history" method="get,put,delete"/>
</links>

Is that wrong? That would allow a client, as well as a bot to be able to
determine what it can do with each resource link.

Furthermore, I thought the use of media types was important? I am still a
bit rusty with this, hence my questions, but I thought there was some push
to use media types like "application/vnd.com.myservice.create+xml" for the
/create resource and that that would be set as the Content-Type on the
request... in Jersey, I'd have a method like this set up:

@POST
@Consumes("application/vnd.com.myservice.create+xml")
public Response create(..){
}

But, in order for a client to know WHAT media type to set the Content-Type
to when sending the request, I'd have to return that media type string in my
links:

<links>
  <link href="http://myservice.com/create" method="post"
type="application/vnd.com.myservice.create+xml"/>
</links>

So that a client, be it a developer consuming my API or a bot scanning the
response, could look at each <link> element, and know that it can
post/put/delete/get and what to set the Content-Type header to so that it
goes to the right method. Naturally the client doesn't know that it will go
to the right method, the point here is that the media type is specific for
each resource. 

So my question is really.. the type="..." portion.. is that what would or
should be done.. passed back as part of a response so that client consumers
can figure out what method(s), URI and media type to set when making a
request? I do NOT mean to say that a client should know BEFORE that this is
what is coming back. Simply that WHEN it comes back, what attributes to look
for in order to make the next request.

If that does not explain it well enough, I don't know what else to say. 

Hi guys,

I wish to create a framework for accessing REST resources over HTTP. I wish to focus on xhtml Content-Type in particular. The idea is that the developer would provide instructions on how to get to the resource from a single URL.

Implementation-wise however, the framework would provide all the necessary plumbing to take care of caching and what not.

Consider three resources:

Root Resource - primary URL ("/"), entry point for the service, has a link to the User List
User List - lists all users, on GET, may accept a query string "email" to search for a specific user, contains link to the users' respective profiles
User Profile - the profile of a user

In order to implement something like get_user_by_email, the developer would have to describe how to get from the Root Resource to the User Profile. In code, a developer using the framework would do something like:

get_user_by_email(email) {
  from("/")
    .on(200) { |Root|
      Root.follow("#users_link")
        .on(200) { |Users|
          Users.fill_in("#search_form", {"email": email})
            .on(200) { |SearchResult|
               SearchResult ...get_first_result...
                 .on(200) { |Profile|
                   return profile_to_some_struct(Profile)
                 }
            }
        }
    }
}

I'm still working on how to best express this intent as code, and it's pretty ugly now I must admit.

However, the framework doesn't really execute the instructions by the developer directly. Instead, it uses its built in cache to get the result. From the example above, the framework would do things in reverse:

1. Is there a cache* of the result to a call to get_user_by_email(email)? If YES, return prior result, If NO, go to step 2
2. Is there a cache of the result to a call getting the search matches of a user given a specified email? If YES, using that result, go down the code -- following the link to the user profile, then returning the result. If NO, go to step 3.
3. Is there a cache of the list of users? If YES, go on and fill in the search form, etc. If NO, go to step 4
4. Is there a cache of the root resource? If YES, go back steps 3,2,1. If NO, get the root resource, and then go further back the steps.

* When I say cached, I generally mean that there has been a prior call, and the result was cached AND the cache hasn't expired yet based on the server cache instructions

The framework forms a tree of possible scenarios. It starts from the most optimistic test (step 1) on the leaf, and if it fails, goes back to its parent.

I believe this would be useful especially if the applications that are going to be built don't follow the UI style of web pages following linked documents. Is this a HATEOAS respecting client? I'd truly appreciate some inputs.

FYI, I'll start development of an Erlang version at http://bitbucket.org/jvliwanag/restr/ . Though, there's nothing there yet now. Hehe.

Jan Vincent Liwanag
jvliwanag@...

Jan

On Feb 27, 2010, at 10:15 AM, Jan Vincent wrote:

> 
> 
> Hi guys,
> 
> I wish to create a framework for accessing REST resources over HTTP. I wish to focus on xhtml Content-Type in particular. The idea is that the developer would provide instructions on how to get to the resource from a single URL.
> 
> Implementation-wise however, the framework would provide all the necessary plumbing to take care of caching and what not.
> 
> Consider three resources:
> 
> Root Resource - primary URL ("/"), entry point for the service, has a link to the User List
> User List - lists all users, on GET, may accept a query string "email" to search for a specific user, contains link to the users' respective profiles
> User Profile - the profile of a user
> 
> In order to implement something like get_user_by_email, the developer would have to describe how to get from the Root Resource to the User Profile. In code, a developer using the framework would do something like:
> 
> get_user_by_email(email) {
>   from("/")
>     .on(200) { |Root|
>       Root.follow("#users_link")
>         .on(200) { |Users|
>           Users.fill_in("#search_form", {"email": email})
>             .on(200) { |SearchResult|
>                SearchResult ...get_first_result...
>                  .on(200) { |Profile|
>                    return profile_to_some_struct(Profile)
>                  }
>             }
>         }
>     }
> }
> 
> I'm still working on how to best express this intent as code, and it's pretty ugly now I must admit.

The problem (from a RESTfulness POV) with this is that the code assumes a certain state machine of the application. If the server decides to change that state machine, the code will break.

If the service publishes information that allows the client to make such assumptions as manifested by the code above, the service is not RESTful but is an "HTTP-based Type I" <http://nordsc.com/ext/classification_of_http_based_apis.html#http-type-one> (or "HTTP-based Type II") API.

If the server does not publish such information the code above just represents guess-work which would be worse because the coupling would actually be hidden inside the code.

When you think about such a framework approach, keep in mind that it will lead to tightly coupled systems no matter how "Webby" the system looks. If the service evolves, the client will break.

Whether this is actually a bad thing depends on the requirements - maybe long term evolvability has been traded for getting something started fast and maybe the expected system lifetime is so short that evolvability does not matter, but you need to be aware of this to make an informed decision.

Jan




> 
> However, the framework doesn't really execute the instructions by the developer directly. Instead, it uses its built in cache to get the result. From the example above, the framework would do things in reverse:
> 
> 1. Is there a cache* of the result to a call to get_user_by_email(email)? If YES, return prior result, If NO, go to step 2
> 2. Is there a cache of the result to a call getting the search matches of a user given a specified email? If YES, using that result, go down the code -- following the link to the user profile, then returning the result. If NO, go to step 3.
> 3. Is there a cache of the list of users? If YES, go on and fill in the search form, etc. If NO, go to step 4
> 4. Is there a cache of the root resource? If YES, go back steps 3,2,1. If NO, get the root resource, and then go further back the steps.
> 
> * When I say cached, I generally mean that there has been a prior call, and the result was cached AND the cache hasn't expired yet based on the server cache instructions
> 
> The framework forms a tree of possible scenarios. It starts from the most optimistic test (step 1) on the leaf, and if it fails, goes back to its parent.
> 
> I believe this would be useful especially if the applications that are going to be built don't follow the UI style of web pages following linked documents. Is this a HATEOAS respecting client? I'd truly appreciate some inputs.
> 
> FYI, I'll start development of an Erlang version at http://bitbucket.org/jvliwanag/restr/ . Though, there's nothing there yet now. Hehe.
> 
> Jan Vincent Liwanag
> jvliwanag@...
> 
> 
> 
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Markus,

Gave you a bad example, yes, create is a command and not a resource. My bad.

So summing up what you said, you did clear up the media type use. For a resource /orders, I would have one media type, say, application/vnd.com.mypackage.orders+xml (perhaps two, with a +json on the end). That would work for ALL resource calls, be it to create, get, put a single item or a list of them. The same one XSD segment would work in all cases. I see that now. Thank you.

I was confused I think partly because of Jan's and some other responses on the Jersey forum regarding using media types for everything. I suppose I thought with how Jersey handles methods for specific media types (even tho you can use the same custom one on multiple methods), I thought perhaps what was meant was to use specific media types for each method (post/put/get/delete) so that you did NOT need to specify in a response link the method to use.

As for the right method to use... you're saying that just like a web page, if I were to copy a link off of a web site, and try to PUT that link to the server, I'd probably get a 405 method not allowed or some error response back. So basically, a list of links that come back to the client in response to a a resource request would simply be a bunch of URIs, that is it. No media type specification, not methods allowed to be called on it. The client consumer simply has to trial and error to the server... if a client calls GET on /orders, and the authentication for the user making that request deems the user can NOT delete/update individual orders, the client UI still shows DELETE/UPDATE links. When the user, whose not allowed to delete/update, clicks one of those links, basically the server responds saying you're not allowed to do this. Is that what I am understanding you to say?

If so, I don't agree with that because I want to build a dynamic UI (if I am a consumer of this API) that gives "hints" so to speak on what a user can do at a given point. I expect my reply to give me the bare minimum essential information so I can represent the users next set of actions correctly. I surely wouldn't want to provide links to delete/update if the user can't do this. There has to be some correct/common/agreed upon/best practices manner in which REST developers are returning these URIs with enough information to allow a client consumer to render a UI that allows its users to make choices it's allowed to make, and not present every possibility. 

So, would you give me an example of how you might do something like this? Show me two xml snippets.. using the same resource (lets use /orders or /cart your choice), one user is only allowed to GET resource items, the other can do the full gamut.. update/delete/get. Show me how you would respond in both scenarios so that I can see how the response URIs are formatted to allow the client consumer to know what can be done and present it as such in a UI to end users.

Thank you.




      

Jan,

On Feb 28, 2010, at 1:17 AM, Jan Vincent wrote:

> I'm not sure again, why some knowledge of the state machine on the server would be a bad thing.

It is bad because it couples client and server. This has the effect that the server owner needs to be aware of its clients to anticipate the impact of change. REST aims to eliminate that coupling.

> The idea I have is something like that of a user browsing through different pages of a website, the difference being is that it is based on some script. Should the server decide to deviate from that script, then yes, things would be screwed up.

Yep - and REST focusses on the server being able to change without things screwing up. This can only be achieved if the client adheres to the hypermedia constraint. Meaning that the client must look at any steady state (that it is being put into by the server) how to proceed to achieve its overall goal. The client must only decide this based on the current steady state after having reached it.

> 
> As such, the content-types provide some form of contract that some elements would need to exist on the representations the restful service serves.

But the client must not make any design time assumptions about the content type it will actually receive.

> In the example provided below, I assume the presence of certain links, and some forms I could fill out.

The hypermedia constraint forbids such assumptions.

This is of course not to say that clients that make such assumptions cannot be appropriate for a given set of requirements. But it is important to understand that the system you end up with is not RESTful because client and server are coupled around these assumptions.

In my opinion, RESTful systems have two essential benefits: Simplicity and eliminating the need for service owners to communicate with client owners when they intend to change the service to support some previously unanticipated requirement (think "business agility").

Simplicity is a huge benefit in itself and achieving it does not depend on adhering to the hypermedia constraint (see my HTTP-based Type I/II). However, being able to evolve the components of a complex system (think "The Web" or "enterprise integration") at an independent pace easily justifies the effort of building a truly RESTful system.

Jan


> I don't really care about the format of the URL, and to some extent, even the methods (since I simply fill out forms on the xhtml representation).
> 
> Moreover, I liken what I have described below as something like tabbed browsing by some user. The user, goes on to the main site, clicks on the lists of users, fills in a form to search for some user and then clicks on the result. If another search is needed, a new 'tab' is opened to save the old resource (say, the setting on the browser is to open the same page on the former tab), hit 'back' to the search users form, and search again.
> 
> On Feb 27, 2010, at 9:21 PM, Jan Algermissen wrote:
> 
>> Jan
>> 
>> On Feb 27, 2010, at 10:15 AM, Jan Vincent wrote:
>> 
>>> 
>>> 
>>> Hi guys,
>>> 
>>> I wish to create a framework for accessing REST resources over HTTP. I wish to focus on xhtml Content-Type in particular. The idea is that the developer would provide instructions on how to get to the resource from a single URL.
>>> 
>>> Implementation-wise however, the framework would provide all the necessary plumbing to take care of caching and what not.
>>> 
>>> Consider three resources:
>>> 
>>> Root Resource - primary URL ("/"), entry point for the service, has a link to the User List
>>> User List - lists all users, on GET, may accept a query string "email" to search for a specific user, contains link to the users' respective profiles
>>> User Profile - the profile of a user
>>> 
>>> In order to implement something like get_user_by_email, the developer would have to describe how to get from the Root Resource to the User Profile. In code, a developer using the framework would do something like:
>>> 
>>> get_user_by_email(email) {
>>> from("/")
>>>   .on(200) { |Root|
>>>     Root.follow("#users_link")
>>>       .on(200) { |Users|
>>>         Users.fill_in("#search_form", {"email": email})
>>>           .on(200) { |SearchResult|
>>>              SearchResult ...get_first_result...
>>>                .on(200) { |Profile|
>>>                  return profile_to_some_struct(Profile)
>>>                }
>>>           }
>>>       }
>>>   }
>>> }
>>> 
>>> I'm still working on how to best express this intent as code, and it's pretty ugly now I must admit.
>> 
>> The problem (from a RESTfulness POV) with this is that the code assumes a certain state machine of the application. If the server decides to change that state machine, the code will break.
>> 
>> If the service publishes information that allows the client to make such assumptions as manifested by the code above, the service is not RESTful but is an "HTTP-based Type I" <http://nordsc.com/ext/classification_of_http_based_apis.html#http-type-one> (or "HTTP-based Type II") API.
>> 
>> If the server does not publish such information the code above just represents guess-work which would be worse because the coupling would actually be hidden inside the code.
>> 
>> When you think about such a framework approach, keep in mind that it will lead to tightly coupled systems no matter how "Webby" the system looks. If the service evolves, the client will break.
>> 
>> Whether this is actually a bad thing depends on the requirements - maybe long term evolvability has been traded for getting something started fast and maybe the expected system lifetime is so short that evolvability does not matter, but you need to be aware of this to make an informed decision.
>> 
>> Jan
>> 
>> 
>> 
>> 
>>> 
>>> However, the framework doesn't really execute the instructions by the developer directly. Instead, it uses its built in cache to get the result. From the example above, the framework would do things in reverse:
>>> 
>>> 1. Is there a cache* of the result to a call to get_user_by_email(email)? If YES, return prior result, If NO, go to step 2
>>> 2. Is there a cache of the result to a call getting the search matches of a user given a specified email? If YES, using that result, go down the code -- following the link to the user profile, then returning the result. If NO, go to step 3.
>>> 3. Is there a cache of the list of users? If YES, go on and fill in the search form, etc. If NO, go to step 4
>>> 4. Is there a cache of the root resource? If YES, go back steps 3,2,1. If NO, get the root resource, and then go further back the steps.
>>> 
>>> * When I say cached, I generally mean that there has been a prior call, and the result was cached AND the cache hasn't expired yet based on the server cache instructions
>>> 
>>> The framework forms a tree of possible scenarios. It starts from the most optimistic test (step 1) on the leaf, and if it fails, goes back to its parent.
>>> 
>>> I believe this would be useful especially if the applications that are going to be built don't follow the UI style of web pages following linked documents. Is this a HATEOAS respecting client? I'd truly appreciate some inputs.
>>> 
>>> FYI, I'll start development of an Erlang version at http://bitbucket.org/jvliwanag/restr/ . Though, there's nothing there yet now. Hehe.
>>> 
>>> Jan Vincent Liwanag
>>> jvliwanag@...
>>> 
>>> 
>>> 
>>> 
>>> 
>>> 
>> 
>> -----------------------------------
>> Jan Algermissen, Consultant
>> NORD Software Consulting
>> 
>> Mail: algermissen@...
>> Blog: http://www.nordsc.com/blog/
>> Work: http://www.nordsc.com/
>> -----------------------------------
>> 
>> 
>> 
>> 
> 
> Jan Vincent Liwanag
> jvliwanag@...
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

After careful thought, I believe I understand HATEOAS better now. My
question however is, since the current resource dictates where I can go,
does this mean that in an application, the UI is highly dependent on which
state I am right now? For web applications, this is understandable. But for
desktop applications, this may not be so. Say, I create a rich address book
app. Assume further that I have a simple feature wherein if I hover on a
contact's entry, I display that contact's brief profile information. How do
I accomplish this? Which resource should I be at?

In addition to this, is it feasible to access multiple REST web services,
thereby maintaining more than one current 'state'?

On Feb 28, 2010, at 9:20 AM, Jan Algermissen wrote:

> Jan,
>
> On Feb 28, 2010, at 1:17 AM, Jan Vincent wrote:
>
>> I'm not sure again, why some knowledge of the state machine on the server
would be a bad thing.
>
> It is bad because it couples client and server. This has the effect that
the server owner needs to be aware of its clients to anticipate the impact
of change. REST aims to eliminate that coupling.
>
>> The idea I have is something like that of a user browsing through
different pages of a website, the difference being is that it is based on
some script. Should the server decide to deviate from that script, then yes,
things would be screwed up.
>
> Yep - and REST focusses on the server being able to change without things
screwing up. This can only be achieved if the client adheres to the
hypermedia constraint. Meaning that the client must look at any steady state
(that it is being put into by the server) how to proceed to achieve its
overall goal. The client must only decide this based on the current steady
state after having reached it.
>
>>
>> As such, the content-types provide some form of contract that some
elements would need to exist on the representations the restful service
serves.
>
> But the client must not make any design time assumptions about the content
type it will actually receive.
>
>> In the example provided below, I assume the presence of certain links,
and some forms I could fill out.
>
> The hypermedia constraint forbids such assumptions.
>
> This is of course not to say that clients that make such assumptions
cannot be appropriate for a given set of requirements. But it is important
to understand that the system you end up with is not RESTful because client
and server are coupled around these assumptions.
>
> In my opinion, RESTful systems have two essential benefits: Simplicity and
eliminating the need for service owners to communicate with client owners
when they intend to change the service to support some previously
unanticipated requirement (think "business agility").
>
> Simplicity is a huge benefit in itself and achieving it does not depend on
adhering to the hypermedia constraint (see my HTTP-based Type I/II).
However, being able to evolve the components of a complex system (think "The
Web" or "enterprise integration") at an independent pace easily justifies
the effort of building a truly RESTful system.
>
> Jan
>
>
>> I don't really care about the format of the URL, and to some extent, even
the methods (since I simply fill out forms on the xhtml representation).
>>
>> Moreover, I liken what I have described below as something like tabbed
browsing by some user. The user, goes on to the main site, clicks on the
lists of users, fills in a form to search for some user and then clicks on
the result. If another search is needed, a new 'tab' is opened to save the
old resource (say, the setting on the browser is to open the same page on
the former tab), hit 'back' to the search users form, and search again.
>>
>> On Feb 27, 2010, at 9:21 PM, Jan Algermissen wrote:
>>
>>> Jan
>>>
>>> On Feb 27, 2010, at 10:15 AM, Jan Vincent wrote:
>>>
>>>>
>>>>
>>>> Hi guys,
>>>>
>>>> I wish to create a framework for accessing REST resources over HTTP. I
wish to focus on xhtml Content-Type in particular. The idea is that the
developer would provide instructions on how to get to the resource from a
single URL.
>>>>
>>>> Implementation-wise however, the framework would provide all the
necessary plumbing to take care of caching and what not.
>>>>
>>>> Consider three resources:
>>>>
>>>> Root Resource - primary URL ("/"), entry point for the service, has a
link to the User List
>>>> User List - lists all users, on GET, may accept a query string "email"
to search for a specific user, contains link to the users' respective
profiles
>>>> User Profile - the profile of a user
>>>>
>>>> In order to implement something like get_user_by_email, the developer
would have to describe how to get from the Root Resource to the User
Profile. In code, a developer using the framework would do something like:
>>>>
>>>> get_user_by_email(email) {
>>>> from("/")
>>>>  .on(200) { |Root|
>>>>    Root.follow("#users_link")
>>>>      .on(200) { |Users|
>>>>        Users.fill_in("#search_form", {"email": email})
>>>>          .on(200) { |SearchResult|
>>>>             SearchResult ...get_first_result...
>>>>               .on(200) { |Profile|
>>>>                 return profile_to_some_struct(Profile)
>>>>               }
>>>>          }
>>>>      }
>>>>  }
>>>> }
>>>>
>>>> I'm still working on how to best express this intent as code, and it's
pretty ugly now I must admit.
>>>
>>> The problem (from a RESTfulness POV) with this is that the code assumes
a certain state machine of the application. If the server decides to change
that state machine, the code will break.
>>>
>>> If the service publishes information that allows the client to make such
assumptions as manifested by the code above, the service is not RESTful but
is an "HTTP-based Type I" <
http://nordsc.com/ext/classification_of_http_based_apis.html#http-type-one>
(or "HTTP-based Type II") API.
>>>
>>> If the server does not publish such information the code above just
represents guess-work which would be worse because the coupling would
actually be hidden inside the code.
>>>
>>> When you think about such a framework approach, keep in mind that it
will lead to tightly coupled systems no matter how "Webby" the system looks.
If the service evolves, the client will break.
>>>
>>> Whether this is actually a bad thing depends on the requirements - maybe
long term evolvability has been traded for getting something started fast
and maybe the expected system lifetime is so short that evolvability does
not matter, but you need to be aware of this to make an informed decision.
>>>
>>> Jan
>>>
>>>
>>>
>>>
>>>>
>>>> However, the framework doesn't really execute the instructions by the
developer directly. Instead, it uses its built in cache to get the result.
From the example above, the framework would do things in reverse:
>>>>
>>>> 1. Is there a cache* of the result to a call to
get_user_by_email(email)? If YES, return prior result, If NO, go to step 2
>>>> 2. Is there a cache of the result to a call getting the search matches
of a user given a specified email? If YES, using that result, go down the
code -- following the link to the user profile, then returning the result.
If NO, go to step 3.
>>>> 3. Is there a cache of the list of users? If YES, go on and fill in the
search form, etc. If NO, go to step 4
>>>> 4. Is there a cache of the root resource? If YES, go back steps 3,2,1.
If NO, get the root resource, and then go further back the steps.
>>>>
>>>> * When I say cached, I generally mean that there has been a prior call,
and the result was cached AND the cache hasn't expired yet based on the
server cache instructions
>>>>
>>>> The framework forms a tree of possible scenarios. It starts from the
most optimistic test (step 1) on the leaf, and if it fails, goes back to its
parent.
>>>>
>>>> I believe this would be useful especially if the applications that are
going to be built don't follow the UI style of web pages following linked
documents. Is this a HATEOAS respecting client? I'd truly appreciate some
inputs.
>>>>
>>>> FYI, I'll start development of an Erlang version at
http://bitbucket.org/jvliwanag/restr/ . Though, there's nothing there yet
now. Hehe.
>>>>
>>>> Jan Vincent Liwanag
>>>> jvliwanag@...
>>>>
>>>>
>>>>
>>>>
>>>>
>>>> 
>>>
>>> -----------------------------------
>>> Jan Algermissen, Consultant
>>> NORD Software Consulting
>>>
>>> Mail: algermissen@...
>>> Blog: http://www.nordsc.com/blog/
>>> Work: http://www.nordsc.com/
>>> -----------------------------------
>>>
>>>
>>>
>>>
>>
>> Jan Vincent Liwanag
>> jvliwanag@...
>>
>>
>>
>
> -----------------------------------
> Jan Algermissen, Consultant
> NORD Software Consulting
>
> Mail: algermissen@...
> Blog: http://www.nordsc.com/blog/
> Work: http://www.nordsc.com/
> -----------------------------------
>
>
>
>

Jan Vincent Liwanag
jvliwanag@...

Kevin,

 

there are several solutions to that. I'll outline three here, there might be
more. The third is the one we recently discussed regards HATEOAS.

 

First of all, your client could invoke the OPTIONS method and inspect the
Allow header
(http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.7) to learn
about the currently allowed (i. e. possible) http methods on one particular
URI. The server is free to decide at that point what he responds, so it
could use the authentication information for example to decide with respect
to the user's access rights, or it could check the resource's state to
dedice with respect to the business status. You client can do that check for
each URI right at the time of receiving it, far before the GUI rendered the
received entity on the screen. This is a rather good method to use if the
media type (see below) is not able to define the link type.

 

Second, if your client just wants to know whether GET is allowed, it could
at that time do a HEAD or GET and cache the result. As HEAD or GET are
idempotent, this is no risk. If HEAD or GET is not allowed, the server would
respond with an Allow header, so you would know what insted is possible. I
see this solution only in special cases.

 

Third and possibly best (and "the" RESTful solution), would be to not use
general link syntax but specific business information. In HTML it is defined
that <A> is a general link, which can be followed solely by HEAD or GET. It
is not defined to use any other http method. So a browser knows a set of
possible and impossible methods just due to the fact that the link is there
and is <A> (in contrast to the link is not there, or the tag being not <A>).
So a HTML aware client can learn from that to either render a link or not,
and to use GET. This is what we currently discuss as "learn from the media
type": The browser knows the media type (here: HTML), so by inspecting the
actual content (here: HTML) it will know from the content what method to use
(here: GET since it is <A>). Let's assume your home-brewn media type. Its
schema could contain the definition of different types of links - not just
<A> but let's say <X> and <Y>. Just as the HTML specification says that <A>
results in HEAD or GET, your home-brewn specification would say that <X> can
only be GET or HEAD, while <Y> could be POST (since it serves as an inbound
for creation of new stuff for example). Since your client is aware of your
home-brewn media type, it will know your specification. As a result, it will
know what the associated http methods are. And your server will either
contain the particular link in the document, or it will abstain, and such
has control the tell the client what currently is possible to do. That's
HATEOAS.

 

Forth, if your business model is rather simple (or it makes sense to turn it
into a simple one), you can just rely on the http specification, which
defines what the methods are good for. In this scenarioa your resources are
such atomic that it is rather clear what POST  / GET / PUT / DELETE will be
good for. That's CRUD. Whether or not this is a useful method on that
resource might be clear from the resource itself or can be learned from the
first solution.

 

Regards

Markus

 

From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com] On
Behalf Of Kevin Duffey
Sent: Samstag, 27. Februar 2010 19:23
To: rest-discuss@yahoogroups.com
Subject: RE: [rest-discuss] Re: [Jersey] Moved thread to rest-discuss /
HATEOAS-via-HTTP: Which HTTP Method to use to follow link?

 







Markus,

Gave you a bad example, yes, create is a command and not a resource. My bad.

So summing up what you said, you did clear up the media type use. For a
resource /orders, I would have one media type, say,
application/vnd.com.mypackage.orders+xml (perhaps two, with a +json on the
end). That would work for ALL resource calls, be it to create, get, put a
single item or a list of them. The same one XSD segment would work in all
cases. I see that now. Thank you.

I was confused I think partly because of Jan's and some other responses on
the Jersey forum regarding using media types for everything. I suppose I
thought with how Jersey handles methods for specific media types (even tho
you can use the same custom one on multiple methods), I thought perhaps what
was meant was to use specific media types for each method
(post/put/get/delete) so that you did NOT need to specify in a response link
the method to use.

As for the right method to use... you're saying that just like a web page,
if I were to copy a link off of a web site, and try to PUT that link to the
server, I'd probably get a 405 method not allowed or some error response
back. So basically, a list of links that come back to the client in response
to a a resource request would simply be a bunch of URIs, that is it. No
media type specification, not methods allowed to be called on it. The client
consumer simply has to trial and error to the server... if a client calls
GET on /orders, and the authentication for the user making that request
deems the user can NOT delete/update individual orders, the client UI still
shows DELETE/UPDATE links. When the user, whose not allowed to
delete/update, clicks one of those links, basically the server responds
saying you're not allowed to do this. Is that what I am understanding you to
say?

If so, I don't agree with that because I want to build a dynamic UI (if I am
a consumer of this API) that gives "hints" so to speak on what a user can do
at a given point. I expect my reply to give me the bare minimum essential
information so I can represent the users next set of actions correctly. I
surely wouldn't want to provide links to delete/update if the user can't do
this. There has to be some correct/common/agreed upon/best practices manner
in which REST developers are returning these URIs with enough information to
allow a client consumer to render a UI that allows its users to make choices
it's allowed to make, and not present every possibility. 

So, would you give me an example of how you might do something like this?
Show me two xml snippets.. using the same resource (lets use /orders or
/cart your choice), one user is only allowed to GET resource items, the
other can do the full gamut.. update/delete/get. Show me how you would
respond in both scenarios so that I can see how the response URIs are
formatted to allow the client consumer to know what can be done and present
it as such in a UI to end users.

Thank you.

On Feb 28, 2010, at 5:30 AM, Jan Vincent wrote:

> After careful thought, I believe I understand HATEOAS better now. My question however is, since the current resource dictates where I can go, does this mean that in an application, the UI is highly dependent on which state I am right now?

Yes, axactly.

> For web applications, this is understandable. But for desktop applications, this may not be so.
> Say, I create a rich address book app. Assume further that I have a simple feature wherein if I hover on a contact's entry, I display that contact's brief profile information. How do I accomplish this? Which resource should I be at?

I'd do this:

Either the data is included in the current state already or the current state includes a link to the data which the client downloads when the user hovers over the contact.

The hypermedia constraint issue here is that the hovering will only display data if the data is there or if that link is available.


> In addition to this, is it feasible to access multiple REST web services, thereby maintaining more than one current 'state'?

Personally, I have not made up my mind on this. I guess that an application is limited to a single service unless the service itself point to another service itself.

Jan

> 
> On Feb 28, 2010, at 9:20 AM, Jan Algermissen wrote:
> 
>> Jan,
>> 
>> On Feb 28, 2010, at 1:17 AM, Jan Vincent wrote:
>> 
>>> I'm not sure again, why some knowledge of the state machine on the server would be a bad thing.
>> 
>> It is bad because it couples client and server. This has the effect that the server owner needs to be aware of its clients to anticipate the impact of change. REST aims to eliminate that coupling.
>> 
>>> The idea I have is something like that of a user browsing through different pages of a website, the difference being is that it is based on some script. Should the server decide to deviate from that script, then yes, things would be screwed up.
>> 
>> Yep - and REST focusses on the server being able to change without things screwing up. This can only be achieved if the client adheres to the hypermedia constraint. Meaning that the client must look at any steady state (that it is being put into by the server) how to proceed to achieve its overall goal. The client must only decide this based on the current steady state after having reached it.
>> 
>>> 
>>> As such, the content-types provide some form of contract that some elements would need to exist on the representations the restful service serves.
>> 
>> But the client must not make any design time assumptions about the content type it will actually receive.
>> 
>>> In the example provided below, I assume the presence of certain links, and some forms I could fill out.
>> 
>> The hypermedia constraint forbids such assumptions.
>> 
>> This is of course not to say that clients that make such assumptions cannot be appropriate for a given set of requirements. But it is important to understand that the system you end up with is not RESTful because client and server are coupled around these assumptions.
>> 
>> In my opinion, RESTful systems have two essential benefits: Simplicity and eliminating the need for service owners to communicate with client owners when they intend to change the service to support some previously unanticipated requirement (think "business agility").
>> 
>> Simplicity is a huge benefit in itself and achieving it does not depend on adhering to the hypermedia constraint (see my HTTP-based Type I/II). However, being able to evolve the components of a complex system (think "The Web" or "enterprise integration") at an independent pace easily justifies the effort of building a truly RESTful system.
>> 
>> Jan
>> 
>> 
>>> I don't really care about the format of the URL, and to some extent, even the methods (since I simply fill out forms on the xhtml representation).
>>> 
>>> Moreover, I liken what I have described below as something like tabbed browsing by some user. The user, goes on to the main site, clicks on the lists of users, fills in a form to search for some user and then clicks on the result. If another search is needed, a new 'tab' is opened to save the old resource (say, the setting on the browser is to open the same page on the former tab), hit 'back' to the search users form, and search again.
>>> 
>>> On Feb 27, 2010, at 9:21 PM, Jan Algermissen wrote:
>>> 
>>>> Jan
>>>> 
>>>> On Feb 27, 2010, at 10:15 AM, Jan Vincent wrote:
>>>> 
>>>>> 
>>>>> 
>>>>> Hi guys,
>>>>> 
>>>>> I wish to create a framework for accessing REST resources over HTTP. I wish to focus on xhtml Content-Type in particular. The idea is that the developer would provide instructions on how to get to the resource from a single URL.
>>>>> 
>>>>> Implementation-wise however, the framework would provide all the necessary plumbing to take care of caching and what not.
>>>>> 
>>>>> Consider three resources:
>>>>> 
>>>>> Root Resource - primary URL ("/"), entry point for the service, has a link to the User List
>>>>> User List - lists all users, on GET, may accept a query string "email" to search for a specific user, contains link to the users' respective profiles
>>>>> User Profile - the profile of a user
>>>>> 
>>>>> In order to implement something like get_user_by_email, the developer would have to describe how to get from the Root Resource to the User Profile. In code, a developer using the framework would do something like:
>>>>> 
>>>>> get_user_by_email(email) {
>>>>> from("/")
>>>>> .on(200) { |Root|
>>>>>   Root.follow("#users_link")
>>>>>     .on(200) { |Users|
>>>>>       Users.fill_in("#search_form", {"email": email})
>>>>>         .on(200) { |SearchResult|
>>>>>            SearchResult ...get_first_result...
>>>>>              .on(200) { |Profile|
>>>>>                return profile_to_some_struct(Profile)
>>>>>              }
>>>>>         }
>>>>>     }
>>>>> }
>>>>> }
>>>>> 
>>>>> I'm still working on how to best express this intent as code, and it's pretty ugly now I must admit.
>>>> 
>>>> The problem (from a RESTfulness POV) with this is that the code assumes a certain state machine of the application. If the server decides to change that state machine, the code will break.
>>>> 
>>>> If the service publishes information that allows the client to make such assumptions as manifested by the code above, the service is not RESTful but is an "HTTP-based Type I" <http://nordsc.com/ext/classification_of_http_based_apis.html#http-type-one> (or "HTTP-based Type II") API.
>>>> 
>>>> If the server does not publish such information the code above just represents guess-work which would be worse because the coupling would actually be hidden inside the code.
>>>> 
>>>> When you think about such a framework approach, keep in mind that it will lead to tightly coupled systems no matter how "Webby" the system looks. If the service evolves, the client will break.
>>>> 
>>>> Whether this is actually a bad thing depends on the requirements - maybe long term evolvability has been traded for getting something started fast and maybe the expected system lifetime is so short that evolvability does not matter, but you need to be aware of this to make an informed decision.
>>>> 
>>>> Jan
>>>> 
>>>> 
>>>> 
>>>> 
>>>>> 
>>>>> However, the framework doesn't really execute the instructions by the developer directly. Instead, it uses its built in cache to get the result. From the example above, the framework would do things in reverse:
>>>>> 
>>>>> 1. Is there a cache* of the result to a call to get_user_by_email(email)? If YES, return prior result, If NO, go to step 2
>>>>> 2. Is there a cache of the result to a call getting the search matches of a user given a specified email? If YES, using that result, go down the code -- following the link to the user profile, then returning the result. If NO, go to step 3.
>>>>> 3. Is there a cache of the list of users? If YES, go on and fill in the search form, etc. If NO, go to step 4
>>>>> 4. Is there a cache of the root resource? If YES, go back steps 3,2,1. If NO, get the root resource, and then go further back the steps.
>>>>> 
>>>>> * When I say cached, I generally mean that there has been a prior call, and the result was cached AND the cache hasn't expired yet based on the server cache instructions
>>>>> 
>>>>> The framework forms a tree of possible scenarios. It starts from the most optimistic test (step 1) on the leaf, and if it fails, goes back to its parent.
>>>>> 
>>>>> I believe this would be useful especially if the applications that are going to be built don't follow the UI style of web pages following linked documents. Is this a HATEOAS respecting client? I'd truly appreciate some inputs.
>>>>> 
>>>>> FYI, I'll start development of an Erlang version at http://bitbucket.org/jvliwanag/restr/ . Though, there's nothing there yet now. Hehe.
>>>>> 
>>>>> Jan Vincent Liwanag
>>>>> jvliwanag@...
>>>>> 
>>>>> 
>>>>> 
>>>>> 
>>>>> 
>>>>> 
>>>> 
>>>> -----------------------------------
>>>> Jan Algermissen, Consultant
>>>> NORD Software Consulting
>>>> 
>>>> Mail: algermissen@...
>>>> Blog: http://www.nordsc.com/blog/
>>>> Work: http://www.nordsc.com/
>>>> -----------------------------------
>>>> 
>>>> 
>>>> 
>>>> 
>>> 
>>> Jan Vincent Liwanag
>>> jvliwanag@...
>>> 
>>> 
>>> 
>> 
>> -----------------------------------
>> Jan Algermissen, Consultant
>> NORD Software Consulting
>> 
>> Mail: algermissen@...
>> Blog: http://www.nordsc.com/blog/
>> Work: http://www.nordsc.com/
>> -----------------------------------
>> 
>> 
>> 
>> 
> 
> Jan Vincent Liwanag
> jvliwanag@...
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Sorry guys, missed the CC on this part.

Begin forwarded message:

> From: Jan Algermissen <algermissen1971@...>
> Date: February 28, 2010 5:17:54 PM GMT+08:00
> To: Jan Vincent <jvliwanag@...>
> Subject: Re: [rest-discuss] Idea for a REST client
> 
> resend to list?
> 
> 
> On Feb 28, 2010, at 2:45 AM, Jan Vincent wrote:
> 
>> Could you perhaps point me to client implementations that are considered RESTful?
>> 
> 
> Umm - no :-)
> 
> I am working on the Jersey client side right now. Should be 1 or two weeks until it is good enough to show something.
> 
> Jan
> 
> 
> 
>> Thanks,
>> 
>> On Feb 28, 2010, at 9:20 AM, Jan Algermissen wrote:
>> 
>>> Jan,
>>> 
>>> On Feb 28, 2010, at 1:17 AM, Jan Vincent wrote:
>>> 
>>>> I'm not sure again, why some knowledge of the state machine on the server would be a bad thing.
>>> 
>>> It is bad because it couples client and server. This has the effect that the server owner needs to be aware of its clients to anticipate the impact of change. REST aims to eliminate that coupling.
>>> 
>>>> The idea I have is something like that of a user browsing through different pages of a website, the difference being is that it is based on some script. Should the server decide to deviate from that script, then yes, things would be screwed up.
>>> 
>>> Yep - and REST focusses on the server being able to change without things screwing up. This can only be achieved if the client adheres to the hypermedia constraint. Meaning that the client must look at any steady state (that it is being put into by the server) how to proceed to achieve its overall goal. The client must only decide this based on the current steady state after having reached it.
>>> 
>>>> 
>>>> As such, the content-types provide some form of contract that some elements would need to exist on the representations the restful service serves.
>>> 
>>> But the client must not make any design time assumptions about the content type it will actually receive.
>>> 
>>>> In the example provided below, I assume the presence of certain links, and some forms I could fill out.
>>> 
>>> The hypermedia constraint forbids such assumptions.
>>> 
>>> This is of course not to say that clients that make such assumptions cannot be appropriate for a given set of requirements. But it is important to understand that the system you end up with is not RESTful because client and server are coupled around these assumptions.
>>> 
>>> In my opinion, RESTful systems have two essential benefits: Simplicity and eliminating the need for service owners to communicate with client owners when they intend to change the service to support some previously unanticipated requirement (think "business agility").
>>> 
>>> Simplicity is a huge benefit in itself and achieving it does not depend on adhering to the hypermedia constraint (see my HTTP-based Type I/II). However, being able to evolve the components of a complex system (think "The Web" or "enterprise integration") at an independent pace easily justifies the effort of building a truly RESTful system.
>>> 
>>> Jan
>>> 
>>> 
>>>> I don't really care about the format of the URL, and to some extent, even the methods (since I simply fill out forms on the xhtml representation).
>>>> 
>>>> Moreover, I liken what I have described below as something like tabbed browsing by some user. The user, goes on to the main site, clicks on the lists of users, fills in a form to search for some user and then clicks on the result. If another search is needed, a new 'tab' is opened to save the old resource (say, the setting on the browser is to open the same page on the former tab), hit 'back' to the search users form, and search again.
>>>> 
>>>> On Feb 27, 2010, at 9:21 PM, Jan Algermissen wrote:
>>>> 
>>>>> Jan
>>>>> 
>>>>> On Feb 27, 2010, at 10:15 AM, Jan Vincent wrote:
>>>>> 
>>>>>> 
>>>>>> 
>>>>>> Hi guys,
>>>>>> 
>>>>>> I wish to create a framework for accessing REST resources over HTTP. I wish to focus on xhtml Content-Type in particular. The idea is that the developer would provide instructions on how to get to the resource from a single URL.
>>>>>> 
>>>>>> Implementation-wise however, the framework would provide all the necessary plumbing to take care of caching and what not.
>>>>>> 
>>>>>> Consider three resources:
>>>>>> 
>>>>>> Root Resource - primary URL ("/"), entry point for the service, has a link to the User List
>>>>>> User List - lists all users, on GET, may accept a query string "email" to search for a specific user, contains link to the users' respective profiles
>>>>>> User Profile - the profile of a user
>>>>>> 
>>>>>> In order to implement something like get_user_by_email, the developer would have to describe how to get from the Root Resource to the User Profile. In code, a developer using the framework would do something like:
>>>>>> 
>>>>>> get_user_by_email(email) {
>>>>>> from("/")
>>>>>> .on(200) { |Root|
>>>>>>  Root.follow("#users_link")
>>>>>>    .on(200) { |Users|
>>>>>>      Users.fill_in("#search_form", {"email": email})
>>>>>>        .on(200) { |SearchResult|
>>>>>>           SearchResult ...get_first_result...
>>>>>>             .on(200) { |Profile|
>>>>>>               return profile_to_some_struct(Profile)
>>>>>>             }
>>>>>>        }
>>>>>>    }
>>>>>> }
>>>>>> }
>>>>>> 
>>>>>> I'm still working on how to best express this intent as code, and it's pretty ugly now I must admit.
>>>>> 
>>>>> The problem (from a RESTfulness POV) with this is that the code assumes a certain state machine of the application. If the server decides to change that state machine, the code will break.
>>>>> 
>>>>> If the service publishes information that allows the client to make such assumptions as manifested by the code above, the service is not RESTful but is an "HTTP-based Type I" <http://nordsc.com/ext/classification_of_http_based_apis.html#http-type-one> (or "HTTP-based Type II") API.
>>>>> 
>>>>> If the server does not publish such information the code above just represents guess-work which would be worse because the coupling would actually be hidden inside the code.
>>>>> 
>>>>> When you think about such a framework approach, keep in mind that it will lead to tightly coupled systems no matter how "Webby" the system looks. If the service evolves, the client will break.
>>>>> 
>>>>> Whether this is actually a bad thing depends on the requirements - maybe long term evolvability has been traded for getting something started fast and maybe the expected system lifetime is so short that evolvability does not matter, but you need to be aware of this to make an informed decision.
>>>>> 
>>>>> Jan
>>>>> 
>>>>> 
>>>>> 
>>>>> 
>>>>>> 
>>>>>> However, the framework doesn't really execute the instructions by the developer directly. Instead, it uses its built in cache to get the result. From the example above, the framework would do things in reverse:
>>>>>> 
>>>>>> 1. Is there a cache* of the result to a call to get_user_by_email(email)? If YES, return prior result, If NO, go to step 2
>>>>>> 2. Is there a cache of the result to a call getting the search matches of a user given a specified email? If YES, using that result, go down the code -- following the link to the user profile, then returning the result. If NO, go to step 3.
>>>>>> 3. Is there a cache of the list of users? If YES, go on and fill in the search form, etc. If NO, go to step 4
>>>>>> 4. Is there a cache of the root resource? If YES, go back steps 3,2,1. If NO, get the root resource, and then go further back the steps.
>>>>>> 
>>>>>> * When I say cached, I generally mean that there has been a prior call, and the result was cached AND the cache hasn't expired yet based on the server cache instructions
>>>>>> 
>>>>>> The framework forms a tree of possible scenarios. It starts from the most optimistic test (step 1) on the leaf, and if it fails, goes back to its parent.
>>>>>> 
>>>>>> I believe this would be useful especially if the applications that are going to be built don't follow the UI style of web pages following linked documents. Is this a HATEOAS respecting client? I'd truly appreciate some inputs.
>>>>>> 
>>>>>> FYI, I'll start development of an Erlang version at http://bitbucket.org/jvliwanag/restr/ . Though, there's nothing there yet now. Hehe.
>>>>>> 
>>>>>> Jan Vincent Liwanag
>>>>>> jvliwanag@gmail.com
>>>>>> 
>>>>>> 
>>>>>> 
>>>>>> 
>>>>>> 
>>>>>> 
>>>>> 
>>>>> -----------------------------------
>>>>> Jan Algermissen, Consultant
>>>>> NORD Software Consulting
>>>>> 
>>>>> Mail: algermissen@...
>>>>> Blog: http://www.nordsc.com/blog/
>>>>> Work: http://www.nordsc.com/
>>>>> -----------------------------------
>>>>> 
>>>>> 
>>>>> 
>>>>> 
>>>> 
>>>> Jan Vincent Liwanag
>>>> jvliwanag@...
>>>> 
>>>> 
>>>> 
>>> 
>>> -----------------------------------
>>> Jan Algermissen, Consultant
>>> NORD Software Consulting
>>> 
>>> Mail: algermissen@...
>>> Blog: http://www.nordsc.com/blog/
>>> Work: http://www.nordsc.com/
>>> -----------------------------------
>>> 
>>> 
>>> 
>>> 
>> 
>> Jan Vincent Liwanag
>> jvliwanag@...m
>> 
>> 
>> 
> 
> -----------------------------------
> Jan Algermissen, Consultant
> NORD Software Consulting
> 
> Mail: algermissen@...
> Blog: http://www.nordsc.com/blog/
> Work: http://www.nordsc.com/
> -----------------------------------
> 
> 
> 
> 

Jan Vincent Liwanag
jvliwanag@...

On Feb 28, 2010, at 11:10 AM, Mark Derricutt wrote:

> Hi,
> 
> Would it be more acceptable with something like this:
> 
>   get_user_by_email(email) {
>     from("/")
>       .on("vnd.myapplication.root", 200) { |Root|
>         Root.follow("#users_link")
> 
> In this minor modification, we're checking for successfully receiving content of a specific media type,

But what does the client do if it does not receive application/vnd.myapplication.root?

> then following a named link which (we shall assume) the media types documentation says will be present.
> 
> My reading of HATEOAS  says we should only need to know the root URL for an API.  With such an API above, I could imagine having multiple on(mediatype, code) blocks for the various media types (or versions of media type) the client can handle.

ah, see. Yes, that is the right direction. Suppose the appication uses the media types A, B and C (client develoiper needs to know which types are used by server, otherwise it could not develop the client in the first place). The programming model is then to decide how to pursue the client's overall goal (e.g. to buy a book) for each of the possible reprsentation types (and status codes of course).

During that process the client might adapt the evaluation rules, which reflects the client advancing through its own intermediate states while it is working towards its goal.

The really challanging part is to come up with a client side API that on the one hand exposes that programming model to force the client developer to apply it but on the other hand to make it intuitive enough to be usable.

The underlying issue really is to 'mediate' between the two state machines (the one of the Web application and the one of the client working towards its goal).

Think of a purchase at Amazon: you enter the site, look for a means to browse through the catalogue, pick an item, put it into the cart, go to check-out and purchase. Within that flow, you go through your own states that change how you interprete the next application state. You need to have reached your own 'watching at list of interesting items' state to actually pick one.

Suppose you entered Amazon with a bookmark of a certain item (maybe because that happened to be the top link in your history) - you interprete that application state differently as you would if you already had chosen that item. What you usually will do is go from the item where you enetered Amazon to the overview page or enter a search directly.

So instead of assuming the entry link will take you to the start page, in your mind you have several rules to interpret the initial application state: if it is the start page start browsing, if it is an item page, go to start page first and then start browsing.

Does that help?


Jan

> 
> Would this be more acceptable in your mind?
> 
> Mark
> 
> 
> -- 
> Pull me down under...
> 
> On Sun, Feb 28, 2010 at 2:21 AM, Jan Algermissen <algermissen1971@...> wrote:
> Jan
> 
> On Feb 27, 2010, at 10:15 AM, Jan Vincent wrote:
> 
> >
> >
> > Hi guys,
> >
> > I wish to create a framework for accessing REST resources over HTTP. I wish to focus on xhtml Content-Type in particular. The idea is that the developer would provide instructions on how to get to the resource from a single URL.
> >
> > Implementation-wise however, the framework would provide all the necessary plumbing to take care of caching and what not.
> >
> > Consider three resources:
> >
> > Root Resource - primary URL ("/"), entry point for the service, has a link to the User List
> > User List - lists all users, on GET, may accept a query string "email" to search for a specific user, contains link to the users' respective profiles
> > User Profile - the profile of a user
> >
> > In order to implement something like get_user_by_email, the developer would have to describe how to get from the Root Resource to the User Profile. In code, a developer using the framework would do something like:
> >
> > get_user_by_email(email) {
> >   from("/")
> >     .on(200) { |Root|
> >       Root.follow("#users_link")
> >         .on(200) { |Users|
> >           Users.fill_in("#search_form", {"email": email})
> >             .on(200) { |SearchResult|
> >                SearchResult ...get_first_result...
> >                  .on(200) { |Profile|
> >                    return profile_to_some_struct(Profile)
> >                  }
> >             }
> >         }
> >     }
> > }
> >
> > I'm still working on how to best express this intent as code, and it's pretty ugly now I must admit.
> 
> The problem (from a RESTfulness POV) with this is that the code assumes a certain state machine of the application. If the server decides to change that state machine, the code will break.
> 
> If the service publishes information that allows the client to make such assumptions as manifested by the code above, the service is not RESTful but is an "HTTP-based Type I" <http://nordsc.com/ext/classification_of_http_based_apis.html#http-type-one> (or "HTTP-based Type II") API.
> 
> If the server does not publish such information the code above just represents guess-work which would be worse because the coupling would actually be hidden inside the code.
> 
> When you think about such a framework approach, keep in mind that it will lead to tightly coupled systems no matter how "Webby" the system looks. If the service evolves, the client will break.
> 
> Whether this is actually a bad thing depends on the requirements - maybe long term evolvability has been traded for getting something started fast and maybe the expected system lifetime is so short that evolvability does not matter, but you need to be aware of this to make an informed decision.
> 
> Jan
> 
> 
> 
> 
> >
> > However, the framework doesn't really execute the instructions by the developer directly. Instead, it uses its built in cache to get the result. From the example above, the framework would do things in reverse:
> >
> > 1. Is there a cache* of the result to a call to get_user_by_email(email)? If YES, return prior result, If NO, go to step 2
> > 2. Is there a cache of the result to a call getting the search matches of a user given a specified email? If YES, using that result, go down the code -- following the link to the user profile, then returning the result. If NO, go to step 3.
> > 3. Is there a cache of the list of users? If YES, go on and fill in the search form, etc. If NO, go to step 4
> > 4. Is there a cache of the root resource? If YES, go back steps 3,2,1. If NO, get the root resource, and then go further back the steps.
> >
> > * When I say cached, I generally mean that there has been a prior call, and the result was cached AND the cache hasn't expired yet based on the server cache instructions
> >
> > The framework forms a tree of possible scenarios. It starts from the most optimistic test (step 1) on the leaf, and if it fails, goes back to its parent.
> >
> > I believe this would be useful especially if the applications that are going to be built don't follow the UI style of web pages following linked documents. Is this a HATEOAS respecting client? I'd truly appreciate some inputs.
> >
> > FYI, I'll start development of an Erlang version at http://bitbucket.org/jvliwanag/restr/ . Though, there's nothing there yet now. Hehe.
> >
> > Jan Vincent Liwanag
> > jvliwanag@...
> >
> >
> >
> >
> >
> >
> 
> -----------------------------------
>  Jan Algermissen, Consultant
>  NORD Software Consulting
> 
>  Mail: algermissen@...
>  Blog: http://www.nordsc.com/blog/
>  Work: http://www.nordsc.com/
> -----------------------------------
> 
> 
> 
> 
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Hello Craid, everyone,

> When using JAX-RS, I'm finding myself more and more often building a
set of JAXB annotated classes that directly represent my resources,
separate from the classes that might represent my domain tier (with,
perhaps, JPA or Hibernate annotations on them). Besides the fact that
this means I don't have to write all of the boring serialization code,
it has some other benefits:

Unfortunately it usually means that you have a new layer that maps
http representations to your domain model... pretty much in the same
way that DTO used to (reminds me of those old J2EE core patterns):
another level of similar structures, with bean data being copied
around.

Kevin's example shows exactly that kind of pattern... I believe thats
the serialization and ORM tool's job to work on their own through
conventions and configuration, with only one model... avoiding that
copy and paste of anemic classes in your code and anemic objects
between layers.

Regards

Guilherme Silveira
Caelum | Ensino e Inova��o
http://www.caelum.com.br/


On Thu, Feb 25, 2010 at 4:37 PM, Craig McClanahan <craigmcc@...> wrote:
>
>
>
> On Thu, Feb 25, 2010 at 9:12 AM, Jan Algermissen
> <algermissen1971@...> wrote:
> >
> > On Feb 25, 2010, at 5:50 PM, Felipe Gaucho wrote:
> >
> >> You can use jaxb and use xml and get a restful service...
> >> There is no mandatory link between these technologies and "non-rest" style...
> >
> > Right, sorry to imply that. OTH, there will often be no 1:1 mapping between domain object (that's how I understood POJO) so if you use JAXB on your POJO you'll rather have a serialized domain object than 'resource representation'
> >
>
> When using JAX-RS, I'm finding myself more and more often building a
> set of JAXB annotated classes that directly represent my resources,
> separate from the classes that might represent my domain tier (with,
> perhaps, JPA or Hibernate annotations on them). Besides the fact that
> this means I don't have to write all of the boring serialization code,
> it has some other benefits:
>
> - Both XML and JSON serialization, nearly for free.
>
> - Ability to include properties for however I'm going to represent
> links (which don't belong in the domain model at all).
>
> - Ability to include properties for related resources (either individual
> child beans or collections of them), for which JAXB does a
> slick job of including as nested sub-elements, versus
> entity beans that are typically associated with only one table.
>
> - Ability to write business logic that is natural to Java
> developers used to beans oriented development,
> independent of the fact that this resource was received
> (or will be sent) across some HTTP or other transport.
>
> - Ablity to write much better unit and functional tests that can
> reason about the resource model (independent of how the
> resources got received from a client or synthesized from my
> database domain objects), with all the usual
> benefits of a strongly typed language (versus using
> XPath or poking through some JSON data structure
> with string based keys and hoping I spelled the keys right).
>
> It's good stuff for Java developers.
>
> Craig
> 

Hi,

Would it be more acceptable with something like this:

  get_user_by_email(email) {
    from("/")
      .on("vnd.myapplication.root", 200) { |Root|
        Root.follow("#users_link")

In this minor modification, we're checking for successfully receiving
content of a specific media type, then following a named link which (we
shall assume) the media types documentation says will be present.

My reading of HATEOAS  says we should only need to know the root URL for an
API.  With such an API above, I could imagine having multiple on(mediatype,
code) blocks for the various media types (or versions of media type) the
client can handle.

Would this be more acceptable in your mind?

Mark


-- 
Pull me down under...

On Sun, Feb 28, 2010 at 2:21 AM, Jan Algermissen <algermissen1971@...>wrote:

> Jan
>
> On Feb 27, 2010, at 10:15 AM, Jan Vincent wrote:
>
> >
> >
> > Hi guys,
> >
> > I wish to create a framework for accessing REST resources over HTTP. I
> wish to focus on xhtml Content-Type in particular. The idea is that the
> developer would provide instructions on how to get to the resource from a
> single URL.
> >
> > Implementation-wise however, the framework would provide all the
> necessary plumbing to take care of caching and what not.
> >
> > Consider three resources:
> >
> > Root Resource - primary URL ("/"), entry point for the service, has a
> link to the User List
> > User List - lists all users, on GET, may accept a query string "email" to
> search for a specific user, contains link to the users' respective profiles
> > User Profile - the profile of a user
> >
> > In order to implement something like get_user_by_email, the developer
> would have to describe how to get from the Root Resource to the User
> Profile. In code, a developer using the framework would do something like:
> >
> > get_user_by_email(email) {
> >   from("/")
> >     .on(200) { |Root|
> >       Root.follow("#users_link")
> >         .on(200) { |Users|
> >           Users.fill_in("#search_form", {"email": email})
> >             .on(200) { |SearchResult|
> >                SearchResult ...get_first_result...
> >                  .on(200) { |Profile|
> >                    return profile_to_some_struct(Profile)
> >                  }
> >             }
> >         }
> >     }
> > }
> >
> > I'm still working on how to best express this intent as code, and it's
> pretty ugly now I must admit.
>
> The problem (from a RESTfulness POV) with this is that the code assumes a
> certain state machine of the application. If the server decides to change
> that state machine, the code will break.
>
> If the service publishes information that allows the client to make such
> assumptions as manifested by the code above, the service is not RESTful but
> is an "HTTP-based Type I" <
> http://nordsc.com/ext/classification_of_http_based_apis.html#http-type-one>
> (or "HTTP-based Type II") API.
>
> If the server does not publish such information the code above just
> represents guess-work which would be worse because the coupling would
> actually be hidden inside the code.
>
> When you think about such a framework approach, keep in mind that it will
> lead to tightly coupled systems no matter how "Webby" the system looks. If
> the service evolves, the client will break.
>
> Whether this is actually a bad thing depends on the requirements - maybe
> long term evolvability has been traded for getting something started fast
> and maybe the expected system lifetime is so short that evolvability does
> not matter, but you need to be aware of this to make an informed decision.
>
> Jan
>
>
>
>
> >
> > However, the framework doesn't really execute the instructions by the
> developer directly. Instead, it uses its built in cache to get the result.
> From the example above, the framework would do things in reverse:
> >
> > 1. Is there a cache* of the result to a call to get_user_by_email(email)?
> If YES, return prior result, If NO, go to step 2
> > 2. Is there a cache of the result to a call getting the search matches of
> a user given a specified email? If YES, using that result, go down the code
> -- following the link to the user profile, then returning the result. If NO,
> go to step 3.
> > 3. Is there a cache of the list of users? If YES, go on and fill in the
> search form, etc. If NO, go to step 4
> > 4. Is there a cache of the root resource? If YES, go back steps 3,2,1. If
> NO, get the root resource, and then go further back the steps.
> >
> > * When I say cached, I generally mean that there has been a prior call,
> and the result was cached AND the cache hasn't expired yet based on the
> server cache instructions
> >
> > The framework forms a tree of possible scenarios. It starts from the most
> optimistic test (step 1) on the leaf, and if it fails, goes back to its
> parent.
> >
> > I believe this would be useful especially if the applications that are
> going to be built don't follow the UI style of web pages following linked
> documents. Is this a HATEOAS respecting client? I'd truly appreciate some
> inputs.
> >
> > FYI, I'll start development of an Erlang version at
> http://bitbucket.org/jvliwanag/restr/ . Though, there's nothing there yet
> now. Hehe.
> >
> > Jan Vincent Liwanag
> > jvliwanag@...
> >
> >
> >
> >
> >
> >
>
> -----------------------------------
>  Jan Algermissen, Consultant
>  NORD Software Consulting
>
>  Mail: algermissen@...
>  Blog: http://www.nordsc.com/blog/
>  Work: http://www.nordsc.com/
> -----------------------------------
>
>
>
>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

Hi all,
>Personally, I have not made up my mind on this. I guess that an application is limited >to a single service unless the service itself point to another service itself.
I don't know that I agree with this, not that you are saying it can or can not be allowed. I believe since the client drives the process, the client can call as many services as it wants to present a valid UI for a user. Think of a web page, where it may call different pages in frames, or separate div css tags. Mashups as well are basically�aggregated�service calls to present multiple things in the UI. I see no reason a client can only use a single URI to start with. �After all, you don't only use a single API call in your own code, there should be no restriction on a client using multiple service resources to build up a single view to the end user. Just my opinion tho.








      

Hey all,


Unfortunately it usually means that you have a new layer that maps
http representations to your domain model... pretty much in the same
way that DTO used to (reminds me of those old J2EE core patterns):
another level of similar structures, with bean data being copied
around.
Are you saying that the J2EE patterns are no longer applicable in general, or for your specific use case? I certainly can understand that if you have a reason for your own situation, but in general, especially if I plan on others working on my code, I'd rather stick to what is well known and usually practiced.

Kevin's example shows exactly that kind of pattern... I believe thats
the serialization and ORM tool's job to work on their own through
conventions and configuration, with only one model... avoiding that
copy and paste of anemic classes in your code and anemic objects
between layers.


Yes, true.. but if you combine the two models into one, while possible, you are requiring your front tier to know about ejb/back end stuff. An even better example of why you would avoid this.. if you were going to use those same XSD generated JAXB classes in a Jersey client (or java client).. and you have the ejb entity annotations in them as well, your client side now has to have the ejb classes to compile. Maybe this is not a big deal, but I personally think that is bad form. I would be confused as a new developer coming aboard a project that was a client side app that had classes annotated with EJB stuff. I'd think they were being stored in a local database and some sort of web/ejb engine was embedded in the client app.
I suppose it really depends on what you will use them for. If it's purely your server side and they are not part of some public API that you plan on sharing, maybe it's fine. I still like the warm fuzzy feeling I get knowing my code is separated and should something arise, I am prepared without any further work needed.



      

> Yes, true.. but if you combine the two models into one, while possible, you
> are requiring your front tier to know about ejb/back end stuff.
>

no, the frontend and its clients are required to know the meta model only ..
a model defined in a XSD schema..  it is the same using or not Java EE..

if you are using Java in the client side, a good practice is to export the
ejb-client jar to be used as domain model .. otherwise the client will
consume the JSON or XML formats generated by the frontend and somehow needs
to understand that.. (you will use a mime-type that indicates that to the
clients, lije application/myapp-xml)

Volume 5 of This week in REST is up on the REST wiki -
http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Feb_22_2010
and the blog - http://wp.me/pMXr1-E. Lot's of interesting links last week!

For contributing links this week visit
http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Mar_1_2010

Cheers!
Ivan

Hello guys

>Are you saying that the J2EE patterns are no longer applicable in general, or for your specific use case?
I believe if our client is a REST client, DTO as we used to do does
not make sense.

According to an old Roy's post: "A REST API should never have �typed�
resources that are significant to the client."
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

It goes on as: "Specification authors may use resource types for
describing server implementation behind the interface, but those types
must be irrelevant and invisible to the client. The only types that
are significant to a client are the current representation�s media
type and standardized relation names."

A typed resource (as this DTO provides to your client) implies in
tighter coupling between both sides, the opposite direction of freedom
that you want.



> Yes, true.. but if you combine the two models into one, while possible, you are requiring your front tier to know about ejb/back end stuff. An even better example of why you would avoid this.. if you were going to use those same XSD generated JAXB classes in a Jersey client (or java client).. and you have the ejb entity annotations in them as well, your client side now has to have the ejb classes to compile.

You are right.. that's why you should not do that. But that is not
what I meant, I probably did not leave it clear enough. Session beans
implies tight coupling by nature: it requires your clients to know and
share the same interface that your server knows, the opposite
direction that REST goes, instead of relation names and media types,
you are using java interfaces and classes. Taking out session beans
and adding rest in its place:

   (dto)      dto                 s-bean                 e-bean
CLIENT --->  WEB TIER --> APP TIER --> DB TIER

becomes:

  (independent model)        resource from here on...
CLIENT -->                        WEB TIER -->
       APP TIER --> DB TIER

What I meant is that it should be your frameworks' responsability to
map the resource representation to your model... while it does not, so
one requires dtos, going back to non-restful architectures.

DTOs are also typically anemic, and because Java classes are closed
(unlike ruby ones), the client will have to live with an anemic DTO
representation of his resource.

That's why I believe DTO and REST should not be together...

Regards

Guilherme Silveira
Caelum | Ensino e Inova��o
http://www.caelum.com.br/

We all agree that the REST interface should be decoupled from domain
models .. BUT, once you make your interface REST it doesn't implies
that you can't benefit for sharing a same model in both client and
server sides.. it would be just waste of resources ...

You should design your REST interface in a way any client can inspect
and reverse engineer the data model but you are not obligated to
ignore the domain model in the client side.. if you have the same
technology in both sides, why not to benefit from it ?

> What I meant is that it should be your frameworks' responsability to
> map the resource representation to your model...

Agree completely and I just don't see why this mapping cannot be an
automagic mapping from JAXB  if JAXb is available n the client side.
:)

ok, it won't be adaptative anymore and once you change the domain
model in the server side you crash the client.. what is a crime for
web crowlers, right ?

If it is about that, please ignore my comments.......



2010/3/1 Felipe Ga�cho <fgaucho@...>:
> We all agree that the REST interface should be decoupled from domain
> models .. BUT, once you make your interface REST it doesn't implies
> that you can't benefit for sharing a same model in both client and
> server sides.. it would be just waste of resources ...
>
> You should design your REST interface in a way any client can inspect
> and reverse engineer the data model but you are not obligated to
> ignore the domain model in the client side.. if you have the same
> technology in both sides, why not to benefit from it ?
>
>> What I meant is that it should be your frameworks' responsability to
>> map the resource representation to your model...
>
> Agree completely and I just don't see why this mapping cannot be an
> automagic mapping from JAXB �if JAXb is available n the client side.
> :)
>



-- 
------------------------------------------
   Felipe Ga�cho
   10+ Java Programmer
   CEJUG Senior Advisor

On 2010-03-02 00.44, Guilherme Silveira wrote:
> DTOs are also typically anemic, and because Java classes are closed
> (unlike ruby ones), the client will have to live with an anemic DTO
> representation of his resource.
>
> That's why I believe DTO and REST should not be together...

When I do "DTO"'s in my REST API, I tend to reuse the same DTO classes 
over and over again. I have "LinksValue" and "LinkValue" being used all 
over the place, rather than type-specific ones. These then get 
serialized to JSON in a predictable way. My client (Swing Java) 
therefore does not have to know all that many DTO classes, and instead 
focus on generic interactions like "select one link from a list and post 
it". So the client code becomes much more reusable, due to the low level 
of coupling.

/Rickard

All -

Recent Jan A published a classification for HTTP-based APIs and I have a question (or questions) related to the distinction between HTTP-based Type II and REST.

For all I can tell, the biggest difference between these two classifications is that HTTP-based Type II assumes the flow of the state machine and REST does not.  I don't understand why the distinction matters.  I've read here that it matters because the server could mix things up and then the client in the hard coded situation would be stuck.  I'd suggest that even in the "REST" scenario, a server could throw a curve ball that will leave the client with no place to go but home.  I think this classification has to more to do with degrees of coupling than it has to do with REST.

Would an automated load tester (client) for a web application that uses hypermedia to traverse the application and execution not be considered RESTful because the state-machine for the application is hard-coded to some degree?

I'd like some clarity on this topic.

Thanks.

Eb

This is a real situation that I will need to deal with in the next year or so.

Farmers raising fruits and vegetables are going online, posting their
locally-available fresh food in a variety of Web apps, including some
that I have written.

Unfortunately, several of these apps exist, sometimes more than one
that a given farmer might want to use: for example, one that sells to
consumers, and another that sells to institutions like hospitals and
schools.

So if a farmer advertises 100 pints of strawberries on 2 such sites,
and consumers buy 75 pints on one site and institutions buy 80 on
another site, the farmer cannot fulfill all the orders, and neither of
the buyers knows that a problem exists.

Moreover, the farmers are getting tired of posting their available
food on more than one site.

So I think about one place (or actually more than one, but one per
farmer) where farmers can go and post their food, which will then
appear on all of the relevant sites, but when ordered, will go back to
the original site.  The original site would need to check availability
and respond back to the buyer with problems, which could also cause
race conditions and vicious circles.  Not a pretty picture.

Is there a RESTful way to handle this situation?

Something vaguely like this, but on steroids?
http://wiki.activitystrea.ms/Actions
http://wiki.developers.facebook.com/index.php/Action_Links

yes, you can use REST to integrate all applications of your business
network.

Data consumers (doesn't matter if hospitals or end customers) can use
clients connected to the farmers servers (directly) to buy goodies.

If well done, data providers and data consumers don't need any agreement in
advance, they need to share only the knowledge about the  mime types.  And
the clients need to know a list of data providers (the servers entry
points). The rest of the conversation can be handled following REST....

The farmers will handle only their own application (data provider), 1 entry
point to maintain.

This way you don't need to "orchestrate" how providers and consumers
communicate each other, it will follow the nature of the web :)

* each farmer will know his current status .. eventually if you need to have
a network information you can create a client to consume the data from the
different applications and then to generate the overall reports...





On Tue, Mar 2, 2010 at 1:06 PM, Bob Haugen <bob.haugen@...> wrote:

>
>
> This is a real situation that I will need to deal with in the next year or
> so.
>
> Farmers raising fruits and vegetables are going online, posting their
> locally-available fresh food in a variety of Web apps, including some
> that I have written.
>
> Unfortunately, several of these apps exist, sometimes more than one
> that a given farmer might want to use: for example, one that sells to
> consumers, and another that sells to institutions like hospitals and
> schools.
>
> So if a farmer advertises 100 pints of strawberries on 2 such sites,
> and consumers buy 75 pints on one site and institutions buy 80 on
> another site, the farmer cannot fulfill all the orders, and neither of
> the buyers knows that a problem exists.
>
> Moreover, the farmers are getting tired of posting their available
> food on more than one site.
>
> So I think about one place (or actually more than one, but one per
> farmer) where farmers can go and post their food, which will then
> appear on all of the relevant sites, but when ordered, will go back to
> the original site. The original site would need to check availability
> and respond back to the buyer with problems, which could also cause
> race conditions and vicious circles. Not a pretty picture.
>
> Is there a RESTful way to handle this situation?
>
> Something vaguely like this, but on steroids?
> http://wiki.activitystrea.ms/Actions
> http://wiki.developers.facebook.com/index.php/Action_Links
>  
>



-- 
------------------------------------------
  Felipe Ga�cho
  10+ Java Programmer
  CEJUG Senior Advisor

On Mar 2, 2010, at 1:06 PM, Bob Haugen wrote:

> This is a real situation that I will need to deal with in the next year or so.
> 
> Farmers raising fruits and vegetables are going online, posting their
> locally-available fresh food in a variety of Web apps, including some
> that I have written.
> 
> Unfortunately, several of these apps exist, sometimes more than one
> that a given farmer might want to use: for example, one that sells to
> consumers, and another that sells to institutions like hospitals and
> schools.
> 
> So if a farmer advertises 100 pints of strawberries on 2 such sites,
> and consumers buy 75 pints on one site and institutions buy 80 on
> another site, the farmer cannot fulfill all the orders, and neither of
> the buyers knows that a problem exists.
> 
> Moreover, the farmers are getting tired of posting their available
> food on more than one site.
> 
> So I think about one place (or actually more than one, but one per
> farmer) where farmers can go and post their food, which will then
> appear on all of the relevant sites, but when ordered, will go back to
> the original site.  The original site would need to check availability
> and respond back to the buyer with problems, which could also cause
> race conditions and vicious circles.  Not a pretty picture.

Why don't the farmers tell the central site that they have 100 pints of strawberries and let the central site deal with the stock management?

Jan

> 
> Is there a RESTful way to handle this situation?
> 
> Something vaguely like this, but on steroids?
> http://wiki.activitystrea.ms/Actions
> http://wiki.developers.facebook.com/index.php/Action_Links
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

On Tue, Mar 2, 2010 at 6:26 AM, Jan Algermissen <algermissen1971@...> wrote:
> Why don't the farmers tell the central site that they have 100 pints of strawberries and let the central site deal with the stock management?
>

There is no central site, or rather, there are 2 or more central sites
where the 100 pints of strawberries will be listed and where buyers
can order.

One of those could be "the" central site, but then how would you
coordinate order conflicts where consumers and institutions try to buy
the same strawberries?

2010/3/2 Felipe Ga�cho <fgaucho@...>
> Data consumers (doesn't matter if hospitals or end customers) can use clients connected to the farmers servers (directly) to buy goodies.
>

The farmers don't have servers, they will post their information on
more than one Web site that offers food from many farmers, but to
different markets.

The orders on those different marketplaces can conflict.

On Mar 2, 2010, at 1:33 PM, Bob Haugen wrote:

> On Tue, Mar 2, 2010 at 6:26 AM, Jan Algermissen <algermissen1971@...> wrote:
>> Why don't the farmers tell the central site that they have 100 pints of strawberries and let the central site deal with the stock management?
>> 
> 
> There is no central site, or rather, there are 2 or more central sites
> where the 100 pints of strawberries will be listed and where buyers
> can order.

So the scenarios is one of N market (-sites) and M farmes that tell each market how much they offer, yes?

Isn't the conflict management 'just' a standard scenario for the need of two phase commits in order to reliably solve the problem? With the note of course that it is not doable in reality and that you just have to live with the uncertaintees? E.g. accept 'overbooking' and over compensation payment to those that did order but not received and goods?

Do you think that the application of REST (or anything else) to the problem changes anything?

Jan


> 
> One of those could be "the" central site, but then how would you
> coordinate order conflicts where consumers and institutions try to buy
> the same strawberries?

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Well, despite your final architecture, the farmers should post
information in just one application. This is the first issue you
should tackle IMO.. (this application can then distribute for several
other apps.. )

That was the tip from Jan ...


2010/3/2 Bob Haugen <bob.haugen@...>:
> 2010/3/2 Felipe Ga�cho <fgaucho@...>
>> Data consumers (doesn't matter if hospitals or end customers) can use clients connected to the farmers servers (directly) to buy goodies.
>>
>
> The farmers don't have servers, they will post their information on
> more than one Web site that offers food from many farmers, but to
> different markets.
>
> The orders on those different marketplaces can conflict.
>



-- 
------------------------------------------
   Felipe Ga�cho
   10+ Java Programmer
   CEJUG Senior Advisor

Eb wrote:
> 
> Would an automated load tester (client) for a web application that
> uses hypermedia to traverse the application and execution not be
> considered RESTful because the state-machine for the application is
> hard-coded to some degree?
> 

Exactly.  My example is an Atom Protocol client's delete function.
Unless you're using a forms language that supports DELETE, to instruct
the client how that function works using hypertext, then the delete
function must be hard-coded in the client chrome.

This works well for deleting members, which is well specified -- but
deleting collections is not.  An Atom Protocol client which hard-codes
a collection-delete function has its interoperability limited to those
systems which interpret collection-delete behavior the same way, i.e.
coupling.

I don't actually care if a collection-delete button is in the client
chrome, so long as its behavior is dictated by received hypertext.
This decoupling allows the server's interpretation of the unspecified
collection-delete function to change, without breaking clients, i.e.
decoupling.

The hypertext constraint is the line between this coupling/decoupling,
and this holds true for a load-tester as well*.  An Atom-Protocol-
centric system with a load-testing REST client that incorporates
collection delete, does not need re-coding in the event of the system
changing.  If it does need re-coding, then it cannot be a REST client,
by definition.

A tightly-coupled client of any sort, even an implementation-specific
load tester, fails to achieve REST if the collection-delete is hard-
coded within.  Xforms for example, allows the server to simply define a
new <model>, within hypertext, dynamically updating all clients when
they next refresh -- without changing the UI (machine or human).

So a load-testing REST client would just be driving an Xforms interface
dynamically.  Refreshing the Xform can reflect the reconfiguration of
the system, without the load-tester needing to care.  It's driving the
same form, which now happens to have a different <model>.

Hard-coding within the client defeats the purpose of the hypertext
constraint, so the result is not a Uniform REST Interface.

-Eric

* I wouldn't necessarily consider a load tester to be a valid use-case
for REST.  I'd hard-code it, since that hard-coding amounts to unit
tests.  REST trades off the efficiencies that a protocol-exercising
client likely requires.

Bob Haugen wrote:
> 
> Is there a RESTful way to handle this situation?
> 

Why bother?  Set up a marketplace on NetSuite and let their Web Service
handle all those issues you point out, charge merchants for stallage.
Granted, a REST API to NetSuite would be nice.  Trying to model that on
rest-discuss, presuming nobody loses interest in the project, could
take years!  ;-)

-Eric

On Mar 2, 2010, at 1:48 PM, Eric J. Bowman wrote:

> Eb wrote:
>> 
>> Would an automated load tester (client) for a web application that
>> uses hypermedia to traverse the application and execution not be
>> considered RESTful because the state-machine for the application is
>> hard-coded to some degree?
>> 
> 
> Exactly.  My example is an Atom Protocol client's delete function.
> Unless you're using a forms language that supports DELETE, to instruct
> the client how that function works using hypertext, then the delete
> function must be hard-coded in the client chrome.

Not quite. The trick is to only show the delete button when there is an 'edit' link in the entry. You break the hypermedia constraint if the button is always there (or clickable) because you assume that the edit link will be there. It might not.

> 
> This works well for deleting members, which is well specified -- but
> deleting collections is not.  An Atom Protocol client which hard-codes
> a collection-delete function has its interoperability limited to those
> systems which interpret collection-delete behavior the same way, i.e.
> coupling.

Deleting collections is not defined by AtomPub so you'd need to do that in a medi atype (extension) first. OTH, HTTP provides sufficient semantics to DELETE any resource. So if you want to build a client that exploits that it might well show a delete button all the time - in the same way a browser shows a GET 'button' all the time (the location bar).


> 
> I don't actually care if a collection-delete button is in the client
> chrome, so long as its behavior is dictated by received hypertext.
> This decoupling allows the server's interpretation of the unspecified
> collection-delete function to change, without breaking clients, i.e.
> decoupling.
> 
> The hypertext constraint is the line between this coupling/decoupling,
> and this holds true for a load-tester as well*.  An Atom-Protocol-
> centric system with a load-testing REST client that incorporates
> collection delete, does not need re-coding in the event of the system
> changing.  If it does need re-coding, then it cannot be a REST client,
> by definition.

Right.


Jan

> 
> A tightly-coupled client of any sort, even an implementation-specific
> load tester, fails to achieve REST if the collection-delete is hard-
> coded within.  Xforms for example, allows the server to simply define a
> new <model>, within hypertext, dynamically updating all clients when
> they next refresh -- without changing the UI (machine or human).
> 
> So a load-testing REST client would just be driving an Xforms interface
> dynamically.  Refreshing the Xform can reflect the reconfiguration of
> the system, without the load-tester needing to care.  It's driving the
> same form, which now happens to have a different <model>.
> 
> Hard-coding within the client defeats the purpose of the hypertext
> constraint, so the result is not a Uniform REST Interface.
> 
> -Eric
> 
> * I wouldn't necessarily consider a load tester to be a valid use-case
> for REST.  I'd hard-code it, since that hard-coding amounts to unit
> tests.  REST trades off the efficiencies that a protocol-exercising
> client likely requires.
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

On Tue, Mar 2, 2010 at 6:47 AM, Jan Algermissen <algermissen1971@...> wrote:
> So the scenarios is one of N market (-sites) and M farmes that tell each market how much they offer, yes?

Yup.  Where N at the moment is 2 or 3, but M is a lot.

> Isn't the conflict management 'just' a standard scenario for the need of two phase commits in order to reliably solve the problem?

Pretty much.

> With the note of course that it is not doable in reality and that you just have to live with the uncertaintees? E.g. accept 'overbooking' and over compensation payment to those that did order but not received and goods?
>

The overbooking will be known and can be communicated well before
compensation payments would be required.

> Do you think that the application of REST (or anything else) to the problem changes anything?

REST does not solve the problem but the REST constraints affect the
problem.  And I don't mean in the sense of "dogmatic rules that must
be obeyed", but in the sense that this problem will exist on the open
Web and thus runs into the problems of coordination over an
untrustworthy network.

So I am interested in "the best that can practically be done" rather
than absolute uncertainty.  In those terms, compensation payments is
not the best that can be done.  Some form of optimistic order taking
with conflict notification seems possible.

Which will leave the problem of how to get the various sites to agree
on the order handling procedure, which will not be easy either.

On Mar 2, 2010, at 12:44 PM, amaeze77 wrote:

> All -
> 
> Recent Jan A published a classification for HTTP-based APIs and I have a question (or questions) related to the distinction between HTTP-based Type II and REST.
> 
> For all I can tell, the biggest difference between these two classifications is that HTTP-based Type II assumes the flow of the state machine and REST does not.

Correct. REST's hypermedia constraint mandates that the client only relies on the current steady state (think "Web page") when deciding what to do next.

> I don't understand why the distinction matters.

Because it decouples the server implementation from the client's expectations. It is the reason why e.g. Amazon can evolve without considering the millions of clients using it. Amazon can even evolve *while* clients are in the middle of a purchase.

>  I've read here that it matters because the server could mix things up and then the client in the hard coded situation would be stuck.  

It matters because REST aims to free the server from having to consider its clients when it evolves.

> I'd suggest that even in the "REST" scenario, a server could throw a curve ball that will leave the client with no place to go but home.

Sure. For those cases, REST emphasizes that the client MUST expect such cases and deal with them instead of considering it to be a violation of some agreement. IOW, any 4xx response is still valid from the POV of the constract that governs the communication. It is not a sign of broken communication.

>  I think this classification has to more to do with degrees of coupling than it has to do with REST.

Huh? REST is essentially about removing any coupling beyond the uniform interface - so that statement does not make sense :-)

> 
> Would an automated load tester (client) for a web application that uses hypermedia to traverse the application and execution not be considered RESTful because the state-machine for the application is hard-coded to some degree?

Why would it be hard-coded?

(Of course you hard-code the knowledge of the media types used, but that is not hard coding the state machine)

Jan

> 
> I'd like some clarity on this topic.
> 
> Thanks.
> 
> Eb
> 
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

On Mar 2, 2010, at 2:03 PM, Bob Haugen wrote:

> 
> REST does not solve the problem but the REST constraints affect the
> problem.  And I don't mean in the sense of "dogmatic rules that must
> be obeyed", but in the sense that this problem will exist on the open
> Web and thus runs into the problems of coordination over an
> untrustworthy network.
> 
> So I am interested in "the best that can practically be done" rather
> than absolute uncertainty.  In those terms, compensation payments is
> not the best that can be done.  Some form of optimistic order taking
> with conflict notification seems possible.
> 
> Which will leave the problem of how to get the various sites to agree
> on the order handling procedure, which will not be easy either.

That sounds like an excellent overall target towards my RESTifying procurement exercise could evolve. If you don't mind, I'll 'steal' your use case for that :-)

I agree that the use of REST affects the problem - will chew on it.

Jan



-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

Jan Algermissen wrote:
> 
> Sure. For those cases, REST emphasizes that the client MUST expect
> such cases and deal with them instead of considering it to be a
> violation of some agreement. IOW, any 4xx response is still valid
> from the POV of the constract that governs the communication. It is
> not a sign of broken communication.
> 

Very well put.  Now I'm going to go off and disagree with you some...

-Eric

Hi Bob,


> So I think about one place (or actually more than one, but one per
> farmer) where farmers can go and post their food, which will then
> appear on all of the relevant sites, but when ordered, will go back to
> the original site.  The original site would need to check availability
> and respond back to the buyer with problems, which could also cause
> race conditions and vicious circles.  Not a pretty picture.

For those in supply-chain management, this is the arena of Distribution Requirements(or resource) Planning.

http://www.enotes.com/management-encyclopedia/distribution-distribution-requirements-planning

The traditional scenario is that of a bookstore where people can post books for sale, like Amazon. DRP was designed before the web so generally each "store" would send a forecast and the DRP system would allocate inventory based on the forecast AND actual orders. That's no longer real-time enough. 

A good example of handling race conditions today is online ticket sales. Tickets (inventory) are reserved for a period of time. If the financial transaction occurs within a given period of time, the tickets are permanently removed from stock. If the basket goes stale, the tickets (inventory) are returned to stock and become available.

This assumes there's a single inventory location. It would take work but your could come up with a peer-based solution using the Amazon model or some other peer-to-peer model like http://www.cs.virginia.edu/papers/vecchio-p2p-IDEAS05.pdf

Mark W.

> Correct. REST's hypermedia constraint mandates that the client only relies
on the current steady state (think "Web page") when deciding what to do
next.

So in the case where a client presupposes the "next" steady state, the
hypermedia constraint has been broken? I'll need to digest that.  :) What
about if I can handle my assumption being incorrect?  Do I get REST points
then?

To your point about Amazon and to extend that example, if I wrote a client
that knew how to order books following a "predefined" state machine (not
wrapped behind some OO classes but trying to use hypermedia explicitly say
via curl) and it broke because Amazon added a new page that my client
couldn't handle, then my client is not RESTful because it assumed what a
response should/would be.  Whereas if my client made zero assumptions (acted
like it didn't know what would be returned even though it indicates its
preference) and didn't ultimately didn't understand what was returned, it
would still be RESTful because it made no assumptions and inspected every
response.

Am I summarizing right?

Eb


On Tue, Mar 2, 2010 at 7:07 AM, Jan Algermissen <algermissen1971@...>wrote:

>
> On Mar 2, 2010, at 12:44 PM, amaeze77 wrote:
>
> > All -
> >
> > Recent Jan A published a classification for HTTP-based APIs and I have a
> question (or questions) related to the distinction between HTTP-based Type
> II and REST.
> >
> > For all I can tell, the biggest difference between these two
> classifications is that HTTP-based Type II assumes the flow of the state
> machine and REST does not.
>
> Correct. REST's hypermedia constraint mandates that the client only relies
> on the current steady state (think "Web page") when deciding what to do
> next.
>
> > I don't understand why the distinction matters.
>
> Because it decouples the server implementation from the client's
> expectations. It is the reason why e.g. Amazon can evolve without
> considering the millions of clients using it. Amazon can even evolve *while*
> clients are in the middle of a purchase.
>
> >  I've read here that it matters because the server could mix things up
> and then the client in the hard coded situation would be stuck.
>
> It matters because REST aims to free the server from having to consider its
> clients when it evolves.
>
> > I'd suggest that even in the "REST" scenario, a server could throw a
> curve ball that will leave the client with no place to go but home.
>
> Sure. For those cases, REST emphasizes that the client MUST expect such
> cases and deal with them instead of considering it to be a violation of some
> agreement. IOW, any 4xx response is still valid from the POV of the
> constract that governs the communication. It is not a sign of broken
> communication.
>
> >  I think this classification has to more to do with degrees of coupling
> than it has to do with REST.
>
> Huh? REST is essentially about removing any coupling beyond the uniform
> interface - so that statement does not make sense :-)
>
> >
> > Would an automated load tester (client) for a web application that uses
> hypermedia to traverse the application and execution not be considered
> RESTful because the state-machine for the application is hard-coded to some
> degree?
>
> Why would it be hard-coded?
>
> (Of course you hard-code the knowledge of the media types used, but that is
> not hard coding the state machine)
>
> Jan
>
> >
> > I'd like some clarity on this topic.
> >
> > Thanks.
> >
> > Eb
> >
> >
> >
> > ------------------------------------
> >
> > Yahoo! Groups Links
> >
> >
> >
>
> -----------------------------------
>  Jan Algermissen, Consultant
>  NORD Software Consulting
>
>  Mail: algermissen@...
>  Blog: http://www.nordsc.com/blog/
>  Work: http://www.nordsc.com/
> -----------------------------------
>
>
>
>
>

On Mar 2, 2010, at 4:02 PM, Eb wrote:

> 
> > Correct. REST's hypermedia constraint mandates that the client only relies on the current steady state (think "Web page") when deciding what to do next.
> 
> So in the case where a client presupposes the "next" steady state, the hypermedia constraint has been broken?

Yes, right.

> I'll need to digest that.  :)


Yeah - it is irritating. OTH, it is more about making explicit that you simply cannot make such assumptions in a networked system rather than some mysterious magic.

Of course the client code eventually assumes it might find that link and provide code for that case but the approach is different and influences how you think about coding the client.

> What about if I can handle my assumption being incorrect?  Do I get REST points then?

In a sense, yes. But the code should try to make explicit that from the current steady state the overall goal of the client cannot be persued any further. IWO, that there is no transition available that it would make sense to follow next. If you just do a try...catch I'd not give you credit :-)

> 
> To your point about Amazon and to extend that example, if I wrote a client that knew how to order books following a "predefined" state machine (not wrapped behind some OO classes but trying to use hypermedia explicitly say via curl) and it broke because Amazon added a new page that my client couldn't handle, then my client is not RESTful because it assumed what a response should/would be.

Yes.


>  Whereas if my client made zero assumptions (acted like it didn't know what would be returned even though it indicates its preference) and didn't ultimately didn't understand what was returned, it would still be RESTful because it made no assumptions and inspected every response.

Yes. Two issues with this:

1. Despite not understanding what was returned, REST emphasizes that there still is communication because you know that you are dealing with a "I do not understand" situation (aka 406 essentially). This is a lot more than 'blurb - fail'. In an enterprise context, you could use the 406 response headers and body to directly instruct developers how to bring the client up to date. This is different from doing an error analysis in an OO system.

2. The way you design your media types greatly influences how gracefully your client can react. In fact, I have come to think that the hypermedia constraint issue is probably the primary aspect of machine-targetted media type design (which we still have no public example of, unfortunately).

Jan


> 
> Am I summarizing right?
> 
> Eb
> 
> 
> On Tue, Mar 2, 2010 at 7:07 AM, Jan Algermissen <algermissen1971@...> wrote:
> 
> On Mar 2, 2010, at 12:44 PM, amaeze77 wrote:
> 
> > All -
> >
> > Recent Jan A published a classification for HTTP-based APIs and I have a question (or questions) related to the distinction between HTTP-based Type II and REST.
> >
> > For all I can tell, the biggest difference between these two classifications is that HTTP-based Type II assumes the flow of the state machine and REST does not.
> 
> Correct. REST's hypermedia constraint mandates that the client only relies on the current steady state (think "Web page") when deciding what to do next.
> 
> > I don't understand why the distinction matters.
> 
> Because it decouples the server implementation from the client's expectations. It is the reason why e.g. Amazon can evolve without considering the millions of clients using it. Amazon can even evolve *while* clients are in the middle of a purchase.
> 
> >  I've read here that it matters because the server could mix things up and then the client in the hard coded situation would be stuck.
> 
> It matters because REST aims to free the server from having to consider its clients when it evolves.
> 
> > I'd suggest that even in the "REST" scenario, a server could throw a curve ball that will leave the client with no place to go but home.
> 
> Sure. For those cases, REST emphasizes that the client MUST expect such cases and deal with them instead of considering it to be a violation of some agreement. IOW, any 4xx response is still valid from the POV of the constract that governs the communication. It is not a sign of broken communication.
> 
> >  I think this classification has to more to do with degrees of coupling than it has to do with REST.
> 
> Huh? REST is essentially about removing any coupling beyond the uniform interface - so that statement does not make sense :-)
> 
> >
> > Would an automated load tester (client) for a web application that uses hypermedia to traverse the application and execution not be considered RESTful because the state-machine for the application is hard-coded to some degree?
> 
> Why would it be hard-coded?
> 
> (Of course you hard-code the knowledge of the media types used, but that is not hard coding the state machine)
> 
> Jan
> 
> >
> > I'd like some clarity on this topic.
> >
> > Thanks.
> >
> > Eb
> >
> >
> >
> > ------------------------------------
> >
> > Yahoo! Groups Links
> >
> >
> >
> 
> -----------------------------------
>  Jan Algermissen, Consultant
>  NORD Software Consulting
> 
>  Mail: algermissen@...
>  Blog: http://www.nordsc.com/blog/
>  Work: http://www.nordsc.com/
> -----------------------------------
> 
> 
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

I know this is an old thread, but I just want to inform other readers that might find it through a search engine, that Microsoft, Google, and Yahoo has put together a solution called "OAuth WRAP".

With WRAP you can present security claims using simple small security tokens called SWT.

There's a pretty good presentation here: http://microsoftpdc.com/Sessions/SVC19 - it refers pretty much to Microsofts Azure Access Control service, but the protocols used are standardized.

Homepage: http://wiki.oauth.net/OAuth-WRAP

Discussion group: http://groups.google.com/group/oauth-wrap-wg

/J�rn

--- In rest-discuss@yahoogroups.com, J�rn Wildt <jw@...> wrote:
> >> Is there any standard RESTful way of doing claims based 
> >> authorization a'la SAML and CardSpace? The authorization schemes I 
> >> have seen so far usually encodes a user reference and nothing more 
> >> - there's no secure way to assert claims like email=xxx@... 
> >> <mailto:email%3Dxxx%40yyy.zz> or
> >> employeenumber=12345 or age-below-twenty.
> >>
> >> I guess you can use SAML "HTTP Redirect (GET) Binding", but that 
> >> generates such a huge URL that it seems impractical to use (it's a 
> >> base-64 encoding of a zip-encoding of a SAML XML document).
> >>
> >> As I understand it a RESTful authorization scheme must be 
> >> stateless, so you cannot rely on any kind of session use. This 
> >> means you have to transfer all the claims on each and every request 
> >> which again means a potentially big overhead.
> >>
> >> What is needed is a standard way of encoding multiple claims in a 
> >> compact, secure, trusted way such that they can be transferred on 
> >> each request without too much overhead (including whatever crypto 
> >> stuff is needed).
> >>
> >> Maybe you could create a temporary ressource somewhere with the 
> >> claims, then at least you only had to transfer the claims URL, not 
> >> all the claims, and the server could then cache these claims.
> >>
> >> Any ideas or references?
> >>
> >> It even occurs to me that claims could be more RESTful than 
> >> username/password since they don't require any out-of-band setup of 
> >> user accounts. All that is needed is a standard for claims and then 
> >> everything should work if the claims are issued by an authority 
> >> that the web service trusts. No need for any human interaction - 
> >> the server just sends a challenge "show me your claims (and I 
> >> accept them from authority X, Y and Z)" whereafter the client sends 
> >> the claims. These claims can even be obtained without human 
> >> interaction if the client and the claims server trust each other.
> >>
> >> Comments?
> >>
> >> Thanks, J�rn
> >
> >
> >
> > ------------------------------------
> >
> > Yahoo! Groups Links
> >
> >
> >
>

Hello Everyone,

Can someone point me to the latest documents/discussions on using REST for
PAYPAL and 3rd Party Payment processors?

Thanks in advance and best regards,
-E

> On 2010-03-02 00.44, Guilherme Silveira wrote:
>> DTOs are also typically anemic, and because Java classes are closed
>> (unlike ruby ones), the client will have to live with an anemic DTO
>> representation of his resource.
>>
>> That's why I believe DTO and REST should not be together...
>
> When I do "DTO"'s in my REST API, I tend to reuse the same DTO classes
> over and over again. I have "LinksValue" and "LinkValue" being used all
> over the place, rather than type-specific ones. These then get
> serialized to JSON in a predictable way. My client (Swing Java)
> therefore does not have to know all that many DTO classes, and instead
> focus on generic interactions like "select one link from a list and post
> it". So the client code becomes much more reusable, due to the low level
> of coupling.

Hello Rickard!

Your case is in the non-typical DTO case :)

>> DTOs are also typically anemic...

Regards

>
> /Rickard
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

Now now, Bob -- stop toying with the kids.  Phil told me back
in the eBuilt days (2000) that you were an expert in inventory
control programs for ERP, so I expect you know the answer to that
problem better than I do.

REST does not have a solution to distributed (more than one
central server) transaction problems, other than to use
server-side intermediaries to change the problem itself.
REST doesn't even try to solve that problem, since it is
behind the server interface.

IIRC, the multi-market problem is known to be intractable
even for strict transaction protocols.  We end up doing the
same thing that everyone else does, which is to use journaling
of orders and either compensating transactions or strict
separation of inventory between sites (with periodic rebalancing
of inventory as stocks decrease).  I think the farmer could
be provided with a RESTful application for tracking and
rebalancing inventory across multiple sites, but I wouldn't
call that a RESTful solution to the inventory problem itself.
It just works well enough to keep the farmer happy.

....Roy

On Tue, Mar 2, 2010 at 8:02 PM, Roy T. Fielding <fielding@...> wrote:
> Now now, Bob -- stop toying with the kids. �Phil told me back
> in the eBuilt days (2000) that you were an expert in inventory
> control programs for ERP, so I expect you know the answer to that
> problem better than I do.

I know how to solve it in ERP, but ERP does not handle this problem.

(That's about all I do these days, work on problems that ERP does not
solve..and most of them happen on the Web, which means I sometimes run
into REST constraints. And sometimes maybe think about them
incorrectly.)

> IIRC, the multi-market problem is known to be intractable
> even for strict transaction protocols. �We end up doing the
> same thing that everyone else does, which is to use journaling
> of orders and either compensating transactions or strict
> separation of inventory between sites (with periodic rebalancing
> of inventory as stocks decrease).

You don't think notifications would work?  Or do you think of them as
compensating transactions?

I'm thinking, by the way, that one resource gets nominated by the
farmer as their inventory resource, and the other markets just display
a representation and then send an update to the inventory resource,
which could respond with an over-order notice.

> �I think the farmer could
> be provided with a RESTful application for tracking and
> rebalancing inventory across multiple sites, but I wouldn't
> call that a RESTful solution to the inventory problem itself.
> It just works well enough to keep the farmer happy.

"Well enough" is all I need.  Farming is like that, too.

But all the separation and rebalancing would have to happen
automatically, without farmer involvement.  So one inventory resource
consumed by multiple markets is an attractive idea, if it can work.

On Mar 3, 2010, at 4:22 AM, Bob Haugen wrote:
> On Tue, Mar 2, 2010 at 8:02 PM, Roy T. Fielding <fielding@...> wrote:
>> IIRC, the multi-market problem is known to be intractable
>> even for strict transaction protocols.  We end up doing the
>> same thing that everyone else does, which is to use journaling
>> of orders and either compensating transactions or strict
>> separation of inventory between sites (with periodic rebalancing
>> of inventory as stocks decrease).
> 
> You don't think notifications would work?  Or do you think of them as
> compensating transactions?

Message (distributed) notifications or database notifications?
They might work -- it depends on how fast the orders are being
processed and how reliable the delivery.  Notification-based
systems tend to fail spectacularly at peak times, and are
usually overkill during non-peak times.   *shrug*  There's a
good chance that you could build a good enough system for family
farms using nothing more than email.

> I'm thinking, by the way, that one resource gets nominated by the
> farmer as their inventory resource, and the other markets just display
> a representation and then send an update to the inventory resource,
> which could respond with an over-order notice.

I thought the sites were independent.  Yes, a single inventory
resource accessed by both sites should be fine as long as the
state changing requests are queued by the implementation.
The implementation of that resource could even be an atomic
test+decrement.  But how are you going to teach the markets
to use such a resource?

>>  I think the farmer could
>> be provided with a RESTful application for tracking and
>> rebalancing inventory across multiple sites, but I wouldn't
>> call that a RESTful solution to the inventory problem itself.
>> It just works well enough to keep the farmer happy.
> 
> "Well enough" is all I need.  Farming is like that, too.
> 
> But all the separation and rebalancing would have to happen
> automatically, without farmer involvement.  So one inventory resource
> consumed by multiple markets is an attractive idea, if it can work.

Yes, if you can make the markets use a shared resource that
is much easier.  If not, then it should also be possible to
automate a balancer even if the farmer's interface to the
markets is two different web pages.   You could then provide
the farmer with mash-up interface that treats the markets as
gateways.

....Roy

Roy,

Thanks for the responses.  And I am sorry if I toyed with the kids,
but this group often helps me think through these kinds of problems,
even if I don't get a ready-made solution (nor do I expect one).

>> You don't think notifications would work? �Or do you think of them as
>> compensating transactions?
>
> Message (distributed) notifications or database notifications?

Message.  Maybe even an HTTP error message?  Then GET the resource again.

> They might work -- it depends on how fast the orders are being
> processed and how reliable the delivery. �Notification-based
> systems tend to fail spectacularly at peak times, and are
> usually overkill during non-peak times. � *shrug* �There's a
> good chance that you could build a good enough system for family
> farms using nothing more than email.

That's the way a lot of them that sell to local consumers work now.
But they are herding into online markets, including several that I
know and help.

> �Yes, a single inventory
> resource accessed by both sites should be fine as long as the
> state changing requests are queued by the implementation.
> The implementation of that resource could even be an atomic
> test+decrement.

Yup.

Wonder if this would help?
http://www.w3.org/1999/04/Editing/

>�But how are you going to teach the markets
> to use such a resource?

So far, not many markets, the people who run them often know each
other, and might be taught to cooperate.

But we'll see.

> if you can make the markets use a shared resource that
> is much easier. �If not, then it should also be possible to
> automate a balancer even if the farmer's interface to the
> markets is two different web pages. � You could then provide
> the farmer with mash-up interface that treats the markets as
> gateways.

A reasonable fall-back.  Thanks again.

I am experimenting with a setup where I base a website completely on a REST API. This means creating the REST API first and then only using that for fetching data to display in the website. This leads to some troubles with URLs for the website - especially how the web URL should identify the REST resources to display.

In a traditional website there is a tight integration to the backend database. This means we can use DB identifiers and readable names in our URLs. Something which most people agree on is good for SEO. Example: to show Peters blog we use the URL http://www.mysite.com/blogs/peter.

But what happens if the backend is a REST API? Now we cannot just write "peter" in the URL since this tells us nothing about how to fetch the "peter" resource. We must instead include the whole URL for the "peter" resource. This URL could be http://rest.mysite.com/feeds/peter which would serve an ATOM feed for our website to format and display nicely. From this follows that our website URL must include the url encoded "peter" reference. Now our URL becomes:

  http://www.mysite.com/blogs/http%3a%2f%2frest.mysite.com%2ffeeds%2fpeter

The downside of this is that our web URL becomes SEO unfriendly, unreadable and impossible to remember. The upside is that we can now display *any* ATOM feed on our website, not just our own feeds, which in turn happens to be both good and bad. It's bad because evil persons can craft a URL with a reference to an evil hackers ATOM feed and make it look like a URL to our site. It's good because it gives us much more flexibility.

I could of course publish a URL template for my ATOM resources, stating that "peter" can be mapped to http://rest.mysite.com/feeds/peter. 

But the use of URL templates makes link relations in the ATOM feed less usefull. A link relation must include the complete URL to the related resource. So an ATOM related link to "older entries" could be http://rest.mysite.com/feeds/peter?page=2. Now we *have* to put this complete reference into our website's URL:

  http://rest.mysite.com/blogs/peter/http%3a%2f%2frest.mysite.com%2ffeeds%2fpeter%3fpage%3d2

So our website's URL becomes more and more obscure if we really don't want to know anything about the REST API's url templates.

Have I missed something? Comments?

Thanks.

I'd like to clear up some misconceptions about URIs and search engines.
The meaning of "SEF URI" should be restricted to "don't use query
strings".  There's nothing "SEO unfriendly" about the URL you posted.
Any advantage to placing keywords in URIs comes down to extreme cases
of tie-breaking where all other things are equal.

Meaning there are a hundred other things you can do for your site to
make it rank better, regardless of your URI allocation scheme.  Lacing
your URIs with keywords is almost completely pointless in this regard.
There's really no connection between your URI allocation scheme's
usability, and either REST or SEO.

Your resource, http://www.mysite.com/blogs/peter, can return anything
you need it to return, regardless of any back-end API.  You can refer
to my demo site for ideas on how to integrate Atom feeds into Web pages
in a direct fashion:

http://charger.bisonsystems.net/xmltest/example.axml
(works cross-browser when /date service is online, lacks CSS for IE)

Client side or server side, you can easily use XSLT to transform an
Atom source into an XHTML page.  Just remember to link to that source
in the result, and use its URI in Content-Location if you're using
conneg to determine whether to return Atom or XHTML for a particular
resource.

I developed the Atom framework first, that's the API, the XHTML is just
transformations.  There's really no need to put the URI of a "REST
resource" into the URI of a request.  If that's how you want your back-
end to look, fine, but you still don't need to expose it to the world.

-Eric

"Jorn Wildt" wrote:
>
> I am experimenting with a setup where I base a website completely on
> a REST API. This means creating the REST API first and then only
> using that for fetching data to display in the website. This leads to
> some troubles with URLs for the website - especially how the web URL
> should identify the REST resources to display.
> 
> In a traditional website there is a tight integration to the backend
> database. This means we can use DB identifiers and readable names in
> our URLs. Something which most people agree on is good for SEO.
> Example: to show Peters blog we use the URL
> http://www.mysite.com/blogs/peter.
> 
> But what happens if the backend is a REST API? Now we cannot just
> write "peter" in the URL since this tells us nothing about how to
> fetch the "peter" resource. We must instead include the whole URL for
> the "peter" resource. This URL could be
> http://rest.mysite.com/feeds/peter which would serve an ATOM feed for
> our website to format and display nicely. From this follows that our
> website URL must include the url encoded "peter" reference. Now our
> URL becomes:
> 
>   http://www.mysite.com/blogs/http%3a%2f%2frest.mysite.com%2ffeeds%2fpeter
> 
> The downside of this is that our web URL becomes SEO unfriendly,
> unreadable and impossible to remember. The upside is that we can now
> display *any* ATOM feed on our website, not just our own feeds, which
> in turn happens to be both good and bad. It's bad because evil
> persons can craft a URL with a reference to an evil hackers ATOM feed
> and make it look like a URL to our site. It's good because it gives
> us much more flexibility.
> 
> I could of course publish a URL template for my ATOM resources,
> stating that "peter" can be mapped to
> http://rest.mysite.com/feeds/peter. 
> 
> But the use of URL templates makes link relations in the ATOM feed
> less usefull. A link relation must include the complete URL to the
> related resource. So an ATOM related link to "older entries" could be
> http://rest.mysite.com/feeds/peter?page=2. Now we *have* to put this
> complete reference into our website's URL:
> 
>   http://rest.mysite.com/blogs/peter/http%3a%2f%2frest.mysite.com%2ffeeds%2fpeter%3fpage%3d2
> 
> So our website's URL becomes more and more obscure if we really don't
> want to know anything about the REST API's url templates.
> 
> Have I missed something? Comments?
> 
> Thanks.
> 
> 

Thanks for the feedback. I'll skip the SEO discussion, that's not the interesting part for me.

> Your resource, http://www.mysite.com/blogs/peter, can return anything
> you need it to return, regardless of any back-end API.

Yes. But I have to point out that www.mysite.com is not the same as my backend rest.mysite.com. The www site has no database in it. It is a simple system that just transforms ATOM feeds exactly like you describe. I don't want the www site to return anything but HTML. If someone wants the ATOM feed, I'll give them the backend REST resource URL.

The point here is that if I construct the REST API first, and build my website on that then I am guaranteed that I have a usefull and working REST API for the rest of the world to use. My system becomes open by design, not as an afterthought.

The interesting point is: how does my www site find the correct ATOM resouce when the only thing it has in it's URL is "peter", as in http://www.mysite.com/blogs/peter.

I can see two solutions: 

1) The www site have apriori knowledge of how to transform "peter" into the backend resource http://rest.mysite.com/feeds/peter

2) The complete resource reference is included in the URL, as in  http://www.mysite.com/blogs/http%3a2f%2frest.mysite.com%2ffeeds%2fpeter

> There's really no need to put the URI of a "REST
> resource" into the URI of a request.

But this is exactly my problem: if I do not want to use apriori information about the REST resource's URL format, then I must include the complete REST URL into my www URL. 

Either I get a very tight integration with my backend REST API, by utilizing apriori information, or I must include complete resource URLs in my www URL.

Consider a situation where the owner of the website merges with another company, leading to a situation where we have two backend REST APIs - the original one, and one for the new company. We want to present both backend datasets on the same www site. Which URL template should I use to convert "peter" into a resource? The original or the new? What if both datasets has a "peter" blog? Now it becomes clearer that putting the full resource URL into my www URL can be nice.


/J�rn

"Jorn Wildt" wrote:
> 
> > Your resource, http://www.mysite.com/blogs/peter, can return
> > anything you need it to return, regardless of any back-end API.
> 
> Yes. But I have to point out that www.mysite.com is not the same as
> my backend rest.mysite.com. The www site has no database in it.
> 

Doesn't matter.  What matters is *that* URIs appear in link relations,
not *what* URIs you are using.

> 
> The interesting point is: how does my www site find the correct ATOM
> resouce when the only thing it has in it's URL is "peter", as in
> http://www.mysite.com/blogs/peter.
> 

By using hypertext and link relations.

> 
> 1) The www site have apriori knowledge of how to transform "peter"
> into the backend resource http://rest.mysite.com/feeds/peter
> 

OK, if you mean transform _from_ the backend resource.  That's the sort
of implementation detail in REST that's opaque behind the interface.

BTW, your website must have this a priori knowledge of the relationship,
otherwise it can't instruct the client about it.

>
> 2) The complete resource reference is included in the URL, as in
> http://www.mysite.com/blogs/http%3a2f%2frest.mysite.com%2ffeeds%2fpeter
> 
> > There's really no need to put the URI of a "REST
> > resource" into the URI of a request.
> 
> But this is exactly my problem: if I do not want to use apriori
> information about the REST resource's URL format, then I must include
> the complete REST URL into my www URL. 
> 

OK, you don't want to use 1), gotcha.  So use hypertext.  What my demo
shows is an XHTML file which calls an XSLT transformation.  The XSLT
code knows what source file to tranform by reading it from the XHTML
file's <link rel='source'/> href (actually from @data, same diff).  For
client-side XSLT like my demo, this has to be from the same domain due
to cross-site restrictions.

A server-side transformation works the same way, though.  REST only
requires that the source file is linked to.  Your <link rel='source'/>
will point to a different domain, is all.  No need to put it in the URI.

>
> Either I get a very tight integration with my backend REST API, by
> utilizing apriori information, or I must include complete resource
> URLs in my www URL.
> 

I'm obviously not agreeing with that 'must include' bit.  You can also
employ headers, including Link.  My demo includes my /date translation
service, which has a different domain.  Due to cross-site restrictions,
I must proxy it from the demo domain.  I just do this using libcurl:

http://charger.bisonsystems.net/date?iso=2010-03-04 simply loads:
http://en.wiski.org/date?iso=2010-03-04 while adding some headers.

There will eventually be language negotiation there, for a multilingual
service.  The headers on charger aren't right, but they do include a
'Content-Location: http://en.wiski.org/date?iso=2010-03-04' header.
That's your 1), there, except what I've done is identify the cross-
domain source in a header -- which is completely RESTful.

>
> Consider a situation where the owner of the website merges with
> another company, leading to a situation where we have two backend
> REST APIs - the original one, and one for the new company. We want to
> present both backend datasets on the same www site. Which URL
> template should I use to convert "peter" into a resource? The
> original or the new? What if both datasets has a "peter" blog? Now it
> becomes clearer that putting the full resource URL into my www URL
> can be nice.
> 

If both datasets have a "peter" blog, they should still have different
atom:id's, so it's easy to create "peter_a" and "peter_b" resources.
I'm still not seeing any problem that requires URIs within URIs here.
Whichever API is used, is reflected in hypertext link relations, inside
markup and/or inside headers.

Disclaimer:  Again, REST has nothing to do with URI design, so my
solution vs. yours has nothing to do with degrees of REST or any such
thing.  The reason I post counter-examples is to steer you away from the
notion that putting URIs in your URIs is somehow required by, or amounts
to following, REST.  What matters is that you're providing the standard
link relations, what (mostly) doesn't matter is the syntax of the URIs
in those link relations (the URIs themselves are opaque, including
domain name).

A "hypertext link relation" can be a <link/> element, a Link: header,
or in my example a Content-Location header.  You can check with RFC
2616bis for current practice on Content-Location, I'm not sure if it's
now allowed as a general response instead of just as a conneg response.

-Eric

> 
> Yes. But I have to point out that www.mysite.com is not the same as
> my backend rest.mysite.com. The www site has no database in it. It is
> a simple system that just transforms ATOM feeds exactly like you
> describe. I don't want the www site to return anything but HTML. If
> someone wants the ATOM feed, I'll give them the backend REST resource
> URL.
> 

If someone wants the Atom feed, they can find it by looking for a link
rel='alternate' with type='application/atom+xml' (you may also use this
link relation to load a source file, instead of rel='source').  Browsers
tend to do this automatically these days, and display an icon for feed
subscription.

If a request comes to www.mysite.com, presumably the default is to
serve an index.html file.  However, if the request only has Accept:
application/atom+xml, you have three options.  First, a 404 response.
Second and third, conneg.

You can serve the Atom source as a 200 response with a Content-Location
header pointing to the rest.mysite.com backend.  Or you can respond
with a 301 redirect with a Location header pointing to the rest.mysite.
com backend.  This "a priori" knowledge on the server's part does not
constitute coupling.

-Eric

>
> First, a 404 response.
> 

Errr, 406.

-Eric

On 4 March 2010 09:28, Jorn Wildt <jw@...> wrote:

>
>  1) The www site have apriori knowledge of how to transform "peter" into
> the backend resource http://rest.mysite.com/feeds/peter
>
> 2) The complete resource reference is included in the URL, as in
> http://www.mysite.com/blogs/http%3a2f%2frest.mysite.com%2ffeeds%2fpeter
>
>
You could use something like the <BASE> tag and then you can have a mix of
both 1 and 2.

Thanks for taking your time to discuss this.

I'll dive right into this statement:

> http://charger.bisonsystems.net/date?iso=2010-03-04 simply loads:
> http://en.wiski.org/date?iso=2010-03-04 while adding some headers.

Now, how does your server know how to transform the incoming http://charger.bisonsystems.net/date?iso=2010-03-04 request to the http://en.wiski.org/date?iso=2010-03-04 location?

You can only do this by having some knowledge of your backend REST API, namely that the URL template is http://en.wiski.org/date?iso={date}. If you did not have this information, how would you then know what to do with the "2010-03-04" value?

> If both datasets have a "peter" blog, they should still have different
> atom:id's, so it's easy to create "peter_a" and "peter_b" resources.

Yes, I understand that. Assuming we keep the original hostname, you could create new resources named http://rest.mysite.com/blogs/peter_a and http://rest.mysite.com/blogs/peter_b based on the ATOM ids.

But what if I don't want to create a new resource "space" for the two companies? I want to keep the old http://rest.mysite.com/feeds/peter and http://rest.anothersite.com/feeds/peter ... well, never mind, I was trying to argue why a URI in a URI could be useful - not discus how to merge companies :-)

> BTW, your website must have this a priori knowledge of the relationship,
> otherwise it can't instruct the client about it.

Not really. I could do a search for "peter" and get back a URL.

The search itself would of course be through the REST API and it could return yet another ATOM feed of the search result (using open search for instance).

Lets see what should be in the search result. Links! Certainly, but links to what? It cannot return links to the www site since that would imply my REST API knew something about it's client. So it must return links to REST API resources. This mean we would get the REST API URL http://rest.mysite.com/feeds/peter back.

Now, what should my www site do with the http://rest.mysite.com/feeds/peter URL in order to generate a browser link to itself that can display the feed? My www site knows nothing about the URL format, so I has no way to figure out how to select "peter" and present a http://www.mysite.com/blogs/peter URL to the end user. And here is my point: the only thing the www site can do, is to include the full REST URL in the www URL.

You could argue that the REST search should return both the complete resource URL as well as the feed name "peter". But then, again, the www site would have to know how to transform "peter" into the REST API URL http://rest.mysite.com/feeds/peter.

/J�rn

> You could argue that the REST search should return both the complete resource URL as well as the feed name "peter". But then, again, the www site would have to know how to transform "peter" into the REST API URL http://rest.mysite.com/feeds/peter.

I would like to add this: what happens if the REST search result suddenly starts to return links to feeds outside of our company space? Maybe it found a good feed on http://johny.com/myblog/feed. The www site would have no way to shorten this URL in it's own URL. All it can do is to include the complete URL.

/J�rn

> > You could argue that the REST search should return both the complete resource URL as well as the feed name "peter". But then, again, the www site would have to know how to transform "peter" into the REST API URL http://rest.mysite.com/feeds/peter.
> 
> I would like to add this: what happens if the REST search result suddenly starts to return links to feeds outside of our company space? Maybe it found a good feed on http://johny.com/myblog/feed. The www site would have no way to shorten this URL in it's own URL. All it can do is to include the complete URL.

The funny thing is that I would have absolutely no problems with handing URLs around if I was building a standalone WPF/Java client. All this is just because "we", as the general internet users, wants nice looking URLs in our browsers. If only browsers would hide that address bar until we wanted to enter something in it :-)

/J�rn

Hey Jorn,

I sent a reply to you a few minutes ago, meant to put it to the list.. if you could so kindly reply and add the list back in to it.

There IS a way to hide that URL line.. and I don't mean actually programatically hiding it with javascript.

I worked on a Swing desktop application that made calls to a server back end a while back, and we had a business need come up to convert it to a web app. We actually installed the web UI on desktops, using Install4J. The app ran just like a desktop app, within a browser on the client, but we embedded tomcat and hsqldb as part of the isntallation. The reason was we had a need to deploy the UI centrally, but also wanted individual users to have it locally to mimic a desktop app. Rather than maintain a Swing desktop app and a web UI, we incorporated the two needs into one web UI.

Anyway, in order to mimic a desktop, we didn't want the URI to be important. We could tell our end users "ignore the URI line..no matter what you see", but that wasn't appropriate. So instead, our www.website.com URI would break the web app into two frames.. a hidden frame of 0 height, and the main frame. In the hidden frame, I loaded all the javascript, downloaded UI images (to cache them in the client), and so on. The UI was purely ajax based, meaning every link/form/etc made ajax calls (to the local tomcat container). The beauty of this was that the URL line remained fixed on our www.website.com URL, while we used javascript and div tags to show/hide portions of the site as needed dynamically. This allowed us to avoid page reloading when a link was clicked, and it kept all the javascript and other "global" variables in the browser memory the entire time the UI was loaded. That way, even if we reloaded the main frame, the javascript was always in
 memory in the hidden frame and didn't have to be reloaded... thus avoiding losing "state" variables and other things.

Just thought I'd share. Not sure if you have considered this approach.


--- On Thu, 3/4/10, Jorn Wildt <jw@...> wrote:

From: Jorn Wildt <jw@...>
Subject: [rest-discuss] Re: Thoughts about URLs for a REST driven website
To: rest-discuss@yahoogroups.com
Date: Thursday, March 4, 2010, 4:48 AM







 



  


    
      
      
      > > You could argue that the REST search should return both the complete resource URL as well as the feed name "peter". But then, again, the www site would have to know how to transform "peter" into the REST API URL http://rest. mysite.com/ feeds/peter.

> 

> I would like to add this: what happens if the REST search result suddenly starts to return links to feeds outside of our company space? Maybe it found a good feed on http://johny. com/myblog/ feed. The www site would have no way to shorten this URL in it's own URL. All it can do is to include the complete URL.



The funny thing is that I would have absolutely no problems with handing URLs around if I was building a standalone WPF/Java client. All this is just because "we", as the general internet users, wants nice looking URLs in our browsers. If only browsers would hide that address bar until we wanted to enter something in it :-)



/Jørn





    
     

    
    


 



  






      

(putting message back on the list)

----- Original Message ----- 
From: "Kevin Duffey" <andjarnic@...>
To: "Jorn Wildt" <jw@...>
Sent: Thursday, March 04, 2010 5:44 PM
Subject: Re: [rest-discuss] Thoughts about URLs for a REST driven website


> I've read the thread you guys got going on. I guess I am not understanding 
> what the problem is. I've utilized REST as a sort of MVC for my web site 
> as well. I look at it this way, the REST API that is available beyond the 
> web to anyone who wants to consume it, ALSO allows me to build my own web 
> UI around it. I do this in one of two ways. One is to have a separate 
> "view" tier web front end. I do this with a simple struts/mvc style web 
> app with JSPs for the view of the web site. When a user clicks on a link 
> that is handled by an action, in that action code I make the REST call to 
> the API, and do all the work inside of the action as needed. The other way 
> I might do it, is to deploy the API within my own UI web app archive. When 
> I do this, I utilize prototype to make ajax calls directly to the REST 
> api, specifying headers, method type, etc as needed. It really depends on 
> which way you want to deploy your API and your front end UI.
>
> I am a little confused on why end users must have some 
> www.mysite.com/peter as their URL? That seems to me that you're passing 
> the REST API uris up to the end user of your UI. I don't quite understand 
> why that is needed or wanted. I don't imagine anyone else using your API 
> from anothter site, or say desktop or mobile client, would somehow use 
> your API URIs within their UI representation of your API. Is there some 
> reason you must incorporate the REST URIs into the front end UI your users 
> would use?
>
>
>
>
>
>
>
>
>
>
>
>
>
>
> 

Kevin, you are describing exactly what I am trying to implement, except for 
the little detail where the whole problem lies:

> When a user clicks on a link that is handled by an action, in that action 
> code I make the REST call to the API

How does that link look? I guess it is something like 
http://www.kevin.com/display-item.jsp?id=1234. Right? I also guess your REST 
API URL is something like http://rest.kevin.com/items/1234. Right?

Now how do you get from the first URL to the second URL? You grap "id=1234" 
from the website URL and paste "1234" into the REST API URL template. This 
means you have apriori knowledge of your REST API.

Okay, this in itself is not such a big problem. You are just utilizing a 
prepublished official bookmark/template URL.

But what if your item contains links to other items? or to purchase orders 
for that item? or to users that bought that item? You know, "hypermedia as 
an engine of application state". The "orders" REST URLs could look like 
http://rest.kevin.com/orders/5678 or 
http://rest.kevin.com/items/1234/orders/5678 - it could even be links to 
orders placed on amazon.com! The point is, you do not know the URL format. 
You can only follow the link and grab the resource found at the endpoint.

Now, on http://www.kevin.com/display-item.jsp?id=1234 we want to have nice 
HTML links to the orders placed on the item. We also want to display the 
order information inside www.kevin.com. What are the URLs for these links? 
You cannot just link to the REST URLs since these do not return HTML, so 
linking to http://rest.kevin.com/items/1234/orders/5678 or 
http://rest.amazon.com/orders/6554 is not an option.

The only solution I see is to include the complete REST order URL in the web 
URL, and thus we end up with:

   http://www.kevin.com/display-item-orders?order=http%3a%2f%2frest.amazon.com%2forders%2f6554

Hopefully this explain why I insist on passing complete URLs around - while 
at the same time I really don't like it because of the ugly URLs.

/J�rn



----- Original Message ----- 
From: "Kevin Duffey" <andjarnic@...>
To: "Jorn Wildt" <jw@...>
Sent: Thursday, March 04, 2010 5:44 PM
Subject: Re: [rest-discuss] Thoughts about URLs for a REST driven website


> I've read the thread you guys got going on. I guess I am not understanding 
> what the problem is. I've utilized REST as a sort of MVC for my web site 
> as well. I look at it this way, the REST API that is available beyond the 
> web to anyone who wants to consume it, ALSO allows me to build my own web 
> UI around it. I do this in one of two ways. One is to have a separate 
> "view" tier web front end. I do this with a simple struts/mvc style web 
> app with JSPs for the view of the web site. When a user clicks on a link 
> that is handled by an action, in that action code I make the REST call to 
> the API, and do all the work inside of the action as needed. The other way 
> I might do it, is to deploy the API within my own UI web app archive. When 
> I do this, I utilize prototype to make ajax calls directly to the REST 
> api, specifying headers, method type, etc as needed. It really depends on 
> which way you want to deploy your API and your front end UI.
>
> I am a little confused on why end users must have some 
> www.mysite.com/peter as their URL? That seems to me that you're passing 
> the REST API uris up to the end user of your UI. I don't quite understand 
> why that is needed or wanted. I don't imagine anyone else using your API 
> from anothter site, or say desktop or mobile client, would somehow use 
> your API URIs within their UI representation of your API. Is there some 
> reason you must incorporate the REST URIs into the front end UI your users 
> would use?
>
>
>
>
>
>
>
>
>
>
>
>
>
>
> 

Hi,

I think we must be thinking different ways of doing this. To me, the front action/mvc/struts/spring/whatever is an API consumer. Like you said, take away the URL line. It's responsible for making API calls and translating the responses from the API into some form of valid HTML.. and likewise, when the user clicks on some link, your front-end should know that <a href="mysite.com?action=GetOrders&user=kevin&id=12345&filterBy=name,phone"> should translate to something like GET http://myservice.com/users/kevin/orders/12345?filterby=name,phone.

Of course the filterBy is just a silly example of adding a query string to it. The point is, if you build your API to be an API and not try to be an API that is ALSO going to be a web front end... you got to think along the API frame of mind. It sounds like you are (or were) planning on building the API first, which seems logical to me. Once the API is done, you build yoru web front end separately. It will "translate" xml/json responses from the API into valid HTML info. Let's say you get a list of orders that you want to display nicely. Your initial call GET /orders returns 5 <order id="..." name="..."/> elements. Now you want to do something with that to make it look nice for the end user. In my mind, I do NOT care what the URL looks like to the end user..they just see links, images, etc that they interact with. The makeup of that link means nothing to your API or the user. So, you want to represent a list of orders in HTML to the user. You have some
 sort of servlet, action, etc that handles when the user clicks that link. The click they do does NOT go straight back to the API layer. You will intercept everything they click on, to translate it as necessary into a valid REST API call. They may get some thml like:

<a href="http://myuisite.com?action=SelectedOrder&orderId=12">Order 12</a>
<a href="http://myuisite.com?action=SelectedOrder&orderId=13">Order 13</a>

when they click one of those, the servlet or action or bean you have mapped to handle the SelectedOrder mapping, gets passed in the orderid request paramter. You pull the ID from that, you then make a call to the REST API� GET /orders/12� filling in the Authorization header, etc as needed to satisfy the REST API. In response, you may get some order details. From that, you either populate a JAX-RS bean (which is what I do when I have webiste "client" call a REST API service), or what have you. You use that response data to then return the JSP, JSF, etc..what ever you have that finally generates the HTML the end user sees.

So.. maybe I am way off.. but that is how I have and will continue to do it until I am told otherwise.

You'll have to forgive me, but I am not entirely sure what apriori knowledge means? If it's what I think it means, you're saying that when you call /orders to get the list of orders.. it would return you orders AND link info regarding those individual orders. So like above, let's say it returns:

<orders>
� <order id="12" name="SomeOrder" href="MyService.com/orders/12"/>
�...
</orders>

Now, when you return this as HTML like I showed above, then the user clicks, your web site will still maintain the "state" of the <orders> items it got back. Order 12 is selected, you search thru your <order> items for 12, you find it, you pull the HREF out of it and you use that URI to make the call to the REST API. I don't see how this is prior knowledge.. the REST API gave you this on the last call. You're web site is basically translating it to HTML and maintaining that state across requests. But that is ok.. its the "client" and it's allowed to maintain state, be it in a HttpSession or using URLRewriting.

I am personally a fan of setting loading up JavaScript and passing various state info to the javascript tier, so as to avoid any HttpSession data. Every single HREF/JavaScript link would then append the "stateful" info back on to the link when making the ajax call. It really depends tho on the amount of data as well. If you got hundreds of users loading up 1000's of orders each, you are going to have to scale your web tier to maintain all that. I still argue that this is the job of a desktop app.. The browser is just an extension of the "client side", and sending that info back for the browser to keep in memory seems trivial to me.

As for responses from the API containing link info to various resources, I've not seen an example of that before, but I would say the web site "client" maintains response data that came back, and maybe provides a few options to the end user, be it a link to the order, or a link elsewhere. You can only present to the end user the info you got back from the API tho. If there are alternative links available, you can provide more links to the end user. Still, the same thing happens. Say you get orders, and history info back. So you set up a different servlet or action to handle the user clicking on a history link. Your web tier server still has all the response data from the API, either in the HttpSession (so that any servlert/action can access it), or passed back to the web client UI so that they can then pass it along on the next request. Either way, you have access to that info so you can make the appropriate REST API call at that point.

Not sure that covers everything you asked about.



      

On Thu, Mar 4, 2010 at 11:43 AM, J�rn Wildt <jw@...> wrote:

Hopefully this explain why I insist on passing complete URLs around - while
> at the same time I really don't like it because of the ugly URLs.
>
>
I try to make my client apps pretty smart, but adding a sense of aesthetics
(so they can "hold their nose" figuratively when invoking an "ugly" URL) is
beyond even my capabilities :-).

More seriously, who cares what the URL looks like, when you should really be
treating them (on the client side) as opaque strings?

From the server perspective, having a predicatable URL template could be
considered a security risk.  I would imagine that applications very
concerned about security are going to be minting random-string URLs
(sometimes even with a limited lifetime) anyway.  Think about the
confirmation message many web sites send when you first sign up, with some
random string of characters included that, if you try to invoke it a year
from now, will simply return a 404.

It's perfectly reasonable for the server application that *created* a URL to
impute some sort of meaning to the URL structure, and thus be tightly bound
to it.  But, from the client perspective, that's an irrelevant
implementation detail.


> /J�rn
>

Craig

PS:  I agree with you on passing complete URLs around, by the way ...
nothing about REST requires that all of the relevant URLs be provided by the
same server.  At the same time, a robust client should support relative URLs
when the media type of the response containing them has well defined
semantics for interpreting them (as HTML does, for example).

Craig, you are right, I know. Well, my logical mind knows. The emotional part of mind has a different opinion. Damn :-)

/J�rn

--- In rest-discuss@yahoogroups.com, Craig McClanahan <craigmcc@...> wrote:
>
> On Thu, Mar 4, 2010 at 11:43 AM, J�rn Wildt <jw@...> wrote:
> 
> Hopefully this explain why I insist on passing complete URLs around - while
> > at the same time I really don't like it because of the ugly URLs.
> >
> >
> I try to make my client apps pretty smart, but adding a sense of aesthetics
> (so they can "hold their nose" figuratively when invoking an "ugly" URL) is
> beyond even my capabilities :-).
> 
> More seriously, who cares what the URL looks like, when you should really be
> treating them (on the client side) as opaque strings?
> 
> From the server perspective, having a predicatable URL template could be
> considered a security risk.  I would imagine that applications very
> concerned about security are going to be minting random-string URLs
> (sometimes even with a limited lifetime) anyway.  Think about the
> confirmation message many web sites send when you first sign up, with some
> random string of characters included that, if you try to invoke it a year
> from now, will simply return a 404.
> 
> It's perfectly reasonable for the server application that *created* a URL to
> impute some sort of meaning to the URL structure, and thus be tightly bound
> to it.  But, from the client perspective, that's an irrelevant
> implementation detail.
> 
> 
> > /J�rn
> >
> 
> Craig
> 
> PS:  I agree with you on passing complete URLs around, by the way ...
> nothing about REST requires that all of the relevant URLs be provided by the
> same server.  At the same time, a robust client should support relative URLs
> when the media type of the response containing them has well defined
> semantics for interpreting them (as HTML does, for example).
>

On Thu, Mar 4, 2010 at 9:52 PM, Jorn Wildt <jw@...> wrote:

>
>
> Craig, you are right, I know. Well, my logical mind knows. The emotional
> part of mind has a different opinion. Damn :-)
>
> I know the feeling.  I also know that (from a client perspective) I
*really* do not want to understand how the sausage factory (i.e. the server)
decided to mint the URLs for this application.

Too.  Much.  Information.  :-)


> /J�rn
>

Craig

PS:  But it's all good in the long run ... if the server application changes
its approach to URL creation, my client is still working fine (as long as I
just faithfully follow the URLs that I'm given), while all those
URL-template folks are off reprogramming to whatever the template de jour
turns out to be.

PPS:  When I'm the server side guy instead of the client side guy, I think
"you mean I can mint obtuse URLs that mean something to *me* even if they
don't mean anything to the client?  Sweet."

Kevin, you are describing exactly what is the most intuitive and most widely implemented way to consume a restful API. Your example is exactly what I am thinking of.

Unfortunately, in a strictly RESTful way, it is also wrong. It completely ignores the HATEOS principle.

See for instance Roy Fieldings (now fameous) rant: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven. Or the Starbucks example: http://www.infoq.com/articles/webber-rest-workflow. Or Subbus post: http://www.subbu.org/blog/2008/09/on-linking-part-1

Consider this situation: your are surfing the web and a friend of yours comes by with an Amazon order ID. "Could you please check this order for me?" he says. "Sure!" you answer. Now what do you do? I am quite sure that you are not going to type the direct Amazon order url into your browser - how would you know what it should look like? But this is equivalent to your suggested REST API consumer - when you pass it an order ID, it utilizes it's apriori ("at design time") knowledge of the REST API's URL structure.

On the user facing web you don't expect to have any knowledge of URL structures. Instead you follow links, do searches, and let the end server calculate the links for you. This is missing link in many REST APIs: they force the client to completely understand the URL structure in order to use the API. This in turns make the client brittle and will cause it to break the first time REST API changes structure.

So for these reasons I cannot see other solutions than handing resource URLs around as parameters in my website URLs.

What I am trying to, is to point out one of the consequences of consuming a truely RESTful API. Namely that your API consumers cannot work with simple item IDs, but have to pass complete resource URLs around.

/J�rn

J�rn,

maybe not exactly to the point of your original question, but...

On Mar 5, 2010, at 6:50 AM, Jorn Wildt wrote:

> What I am trying to, is to point out one of the consequences of consuming a truely RESTful API. Namely that your API consumers cannot work with simple item IDs, but have to pass complete resource URLs around.

It is ok to use IDs to refer to server side 'things' as long as the client discovers them in hypermedia. For example, an HTML form with a bunch of IDs presented in <option> elements in a select control does not violate the hypermedia constraint. IOW, you need not put URIs in the options just to be RESTful.

Likewise, it is ok to have a URI template like /users/{userId} if the link relation defines the meaning of the userId param and if the client discovers user IDs in received representations.

Jan


-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

> maybe not exactly to the point of your original question, but...

It certainly is right to the point :-)

> It is ok to use IDs to refer to server side 'things' as long as the client discovers them in hypermedia. For example, an HTML form with a bunch of IDs presented in <option> elements in a select control does not violate the hypermedia constraint. IOW, you need not put URIs in the options just to be RESTful.

This only works because your website behind the form knows how to map IDs from the <option> element to resource URLs on it's backend REST API. When the user posts the form I assume the result is something like this:

  POST /show-item.aspx?id=1234 HTTP/1.1

How does the webserver know how to map "1234" into it's backend resource http://rest.mysite.com/items/1234? 

Your website is certainly RESTful on the user facing part. But it's interaction with the backend REST API is not.

Notice that we don't have this issue when our backend is a database. In that case there is a really tight coupling between the website and the DB - the website know exactly how to fetch items from the DB using IDs only.


> Likewise, it is ok to have a URI template like /users/{userId} if the link relation defines the meaning of the userId param and if the client discovers user IDs in received representations.

Okay, that might work. Lets explore that solution. Assume we have a REST API for searching our items. The search API has one official URL that lets us search items by name:

  http://rest.mysite.com/items?name={name}
  
The search returns an ATOM feed with found items (ATOM entries):

  <entry>
    <title>Playstation</title>
	<id>1234</id>
	<link rel="self">http://rest.mysite.com/items/1234</link>
  <entry>
  
  <entry>
    <title>Commodore 64</title>
	<id>1234</id>
	<link rel="self">http://rest.mysite.com/olditems/1234</link>
  <entry>
  
Check the "self" links. The resource format is not the same for the two items. So I cannot just grab the ID and render HTML anchors with them since the "commodere 64" link would be wrong.

I want to render the search result as an HTML list with links to my user facing web:

  <ul>
    <li>
      <a href="http://www.mysite.com/display-item.aspx?id=1234">Playstation</a>
    </li>
    <li>
      <a href="http://www.mysite.com/display-item.aspx?id=1234">Commodore 64</a>
    </li>
  </ul>

Notice how my two items suddenly have the same user facing URL!

Now lets add URL templates in the result as you suggest. I do not know of such a thing, so I'll create my own:

  <entry>
    <title>Playstation</title>
	<id>1234</id>
	<link-template rel="self" param="id">http://rest.mysite.com/items/{id}</link>
	<link rel="self">http://rest.mysite.com/items/1234</link>
  <entry>
  
  <entry>
    <title>Commodore 64</title>
	<id>1234</id>
	<link-template rel="self" param="id">http://rest.mysite.com/olditems/{id}</link>
	<link rel="self">http://rest.mysite.com/olditems/1234</link>
  <entry>

Now, having this template information, we can construct resource URLs our self. But to do so we must pass the template together with the ID, otherwise our display-item webpage won't know how to generate the resource URL.

So the HTLM becomes:

  <ul>
    <li>
      <a href="http://www.mysite.com/display-item.aspx?id=1234&template=http://rest.mysite.com/items/{id}">Playstation</a>
    </li>
    <li>
      <a href="http://www.mysite.com/display-item.aspx?id=1234&template=http://rest.mysite.com/olditems/{id}">Commodore 64</a>
    </li>
  </ul>

This works ... but I would rather just include the real resource URL instead of both the ID and the template.

So again I must conclude that a consequence of using a REST backend, is that we must pass complete resource URLs around in our website URLs. Adhering stricly to a backend REST API means loosing the ability to use short URLs in the user facing frontend.

/J�rn

On Mar 5, 2010, at 9:48 AM, Jorn Wildt wrote:

>> maybe not exactly to the point of your original question, but...
> 
> It certainly is right to the point :-)
> 
>> It is ok to use IDs to refer to server side 'things' as long as the client discovers them in hypermedia. For example, an HTML form with a bunch of IDs presented in <option> elements in a select control does not violate the hypermedia constraint. IOW, you need not put URIs in the options just to be RESTful.
> 
> This only works because your website behind the form knows how to map IDs from the <option> element to resource URLs on it's backend REST API. When the user posts the form I assume the result is something like this:
> 
>  POST /show-item.aspx?id=1234 HTTP/1.1
> 
> How does the webserver know how to map "1234" into it's backend resource http://rest.mysite.com/items/1234? 

Eh.....from a form!? It must act as a RESTful client to the backend RESTful service. Otherwise you would be in portal-land....

> 
> Your website is certainly RESTful on the user facing part. But it's interaction with the backend REST API is not.
> 

Then make it so

> Notice that we don't have this issue when our backend is a database. In that case there is a really tight coupling between the website and the DB - the website know exactly how to fetch items from the DB using IDs only.
> 
> 
>> Likewise, it is ok to have a URI template like /users/{userId} if the link relation defines the meaning of the userId param and if the client discovers user IDs in received representations.
> 
> Okay, that might work. Lets explore that solution. Assume we have a REST API for searching our items. The search API has one official URL that lets us search items by name:
> 
>  http://rest.mysite.com/items?name={name}
> 
> The search returns an ATOM feed with found items (ATOM entries):
> 
>  <entry>
>    <title>Playstation</title>
> 	<id>1234</id>
> 	<link rel="self">http://rest.mysite.com/items/1234</link>
>  <entry>
> 
>  <entry>
>    <title>Commodore 64</title>
> 	<id>1234</id>
> 	<link rel="self">http://rest.mysite.com/olditems/1234</link>
>  <entry>
> 
> Check the "self" links. The resource format is not the same for the two items. So I cannot just grab the ID and render HTML anchors with them since the "commodere 64" link would be wrong.

Then the 'form' that the backend gave to the service is simply wrong. In your example, there are two different construction rules (forms) for different context. Why would you do that? Why not just one form? The server can sort out the old vs new stuff behind the interface.

(Note: your link syntax is wrong. should be href="")

> 
> I want to render the search result as an HTML list with links to my user facing web:
> 
>  <ul>
>    <li>
>      <a href="http://www.mysite.com/display-item.aspx?id=1234">Playstation</a>
>    </li>
>    <li>
>      <a href="http://www.mysite.com/display-item.aspx?id=1234">Commodore 64</a>
>    </li>
>  </ul>
> 
> Notice how my two items suddenly have the same user facing URL!

And?


> 
> Now lets add URL templates in the result as you suggest. I do not know of such a thing, so I'll create my own:
> 
>  <entry>
>    <title>Playstation</title>
> 	<id>1234</id>
> 	<link-template rel="self" param="id">http://rest.mysite.com/items/{id}</link>
> 	<link rel="self">http://rest.mysite.com/items/1234</link>
>  <entry>
> 
>  <entry>
>    <title>Commodore 64</title>
> 	<id>1234</id>
> 	<link-template rel="self" param="id">http://rest.mysite.com/olditems/{id}</link>
> 	<link rel="self">http://rest.mysite.com/olditems/1234</link>
>  <entry>

You only need one template, not one per entry. Also I would put that into some service document and not into the search result.

> 
> Now, having this template information, we can construct resource URLs our self. But to do so we must pass the template together with the ID, otherwise our display-item webpage won't know how to generate the resource URL.
> 
> So the HTLM becomes:
> 
>  <ul>
>    <li>
>      <a href="http://www.mysite.com/display-item.aspx?id=1234&template=http://rest.mysite.com/items/{id}">Playstation</a>
>    </li>
>    <li>
>      <a href="http://www.mysite.com/display-item.aspx?id=1234&template=http://rest.mysite.com/olditems/{id}">Commodore 64</a>
>    </li>
>  </ul>
> 
> This works ... but I would rather just include the real resource URL instead of both the ID and the template.
> 
> So again I must conclude that a consequence of using a REST backend, is that we must pass complete resource URLs around in our website URLs. Adhering stricly to a backend REST API means loosing the ability to use short URLs in the user facing frontend.

There is something wrong in your overall thinking.

You'd just have the fron Web app that exposes a RESTful API. It would then interact RESTfully with a RESTful backend. It is simply 'wrong' to relate the URIs of the backend in any way to the URIs of the forntend. You do not even have to make use of the same IDs as long as the frontend service keeps its own mapping table.

HTH,
Jan


> 
> /J�rn
> 
> 
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------

> >  POST /show-item.aspx?id=1234 HTTP/1.1
> > 
> > How does the webserver know how to map "1234" into it's backend resource http://rest.mysite.com/items/1234? 
> 
> Eh.....from a form!? It must act as a RESTful client to the backend RESTful service. Otherwise you would be in portal-land....

Ok. Sorry. I thought you were talking about a user facing form. Not a form on the REST API. That makes sense.

I assume you discover the form at runtime, not designtime. Right? But you have to know at designtime that <input name="itemname"/> is the input you want to put the item's name in. Right? That's great - we have to know something about the parameters at designtime, but we avoid knowing anything about URLs until runtime.


> > Check the "self" links. The resource format is not the same for the two items. So I cannot just grab the ID and render HTML anchors with them since the "commodere 64" link would be wrong.
> 
> Then the 'form' that the backend gave to the service is simply wrong. In your example, there are two different construction rules (forms) for different context. Why would you do that? Why not just one form? The server can sort out the old vs new stuff behind the interface.

The server can only sort out the old vs. new stuff if it somehow encodes new/old in the ID. Could be "old1234" vs. "new1234". That works. But you are starting to invent your own URI format ... that would not be necessary if you simply included the whole resource URL.

> You'd just have the fron Web app that exposes a RESTful API. It would then interact RESTfully with a RESTful backend. It is simply 'wrong' to relate the URIs of the backend in any way to the URIs of the forntend. You do not even have to make use of the same IDs as long as the frontend service keeps its own mapping table.

But the whole point is to build a database-less website that completely depends on a REST API for it to work. There is no "state" in the website, no place to save that mapping table. That's the path I am exploring. By doing so my website will be open by design instead of adding REST APIs as an afterthought. It will be possibe to write a new .NET/Java client without changing a single line of code in the website. Instead of building the REST API on top of the website, I want to build my clients on top of the API - and by client I mean both HTML, .NET and Java.

Anyway, I think I have used up my amount of time from you guys on this. Thanks a lot. It has been interesting. You are of course welcome to reply, but there is no expectation on it on my part.

/J�rn

> This only works because your website behind the form knows how to map IDs from 
> the  element to resource URLs on it's backend REST API. When the user 
> posts the form I assume the result is something like this:
> 
>   POST /show-item.aspx?id=1234 HTTP/1.1
> 
> How does the webserver know how to map "1234" into it's backend resource 
> http://rest.mysite.com/items/1234? 

Isn't that what libraries are for? Java has Jersey (JAX-RS) to map from your URI to method calls and a URI-builder to create state links.

Mark W.

Hi,

If I understand HATEOAS correctly, if I make a /orders call, get back a list of orders with links on what I can do next, the server at this point has no "state" memory.. it has no idea after it sent back the response, that it just told me "here is what you can do now". I could come back 3 years later, and use those URIs it sent back to me and it should work. Is that not correct?

As for giving it to someone else, well, they would first have to pass authentication as far as I know. But that does raise an interesting question. Using your example, how would the RESTful api "prevent" any call being made from anyone if they authenticate? That is, if you and I are both authenticated users, and you pull a /orders with your info, and it gives you a list back for your orders, you could then give me the URIs it returns, and I could make those same calls on your behalf, using my authentication. Correct? My only guess is that every single call made to a RESTful API should perform validation checks which would be expensive I suppose if every time I tried to call one of your URIs for a specific order, the RESTful api had to verify that the user making the call is the same user that received the URIs in the first place.  I am not sure if that makes sense, rereading it, but I am curious how this sort of issue is prevented. Generally, you
 wouldn't hand me your URIs that you got back, but a man-in-the-middle could easily catch those URIs (assuming that person defeated SSL when going over SSL). So how is such a scenario handled.. or should be handled by REST apis?



Consider this situation: your are surfing the web and a friend of yours comes by with an Amazon order ID. "Could you please check this order for me?" he says. "Sure!" you answer. Now what do you do? I am quite sure that you are not going to type the direct Amazon order url into your browser - how would you know what it should look like? But this is equivalent to your suggested REST API consumer - when you pass it an order ID, it utilizes it's apriori ("at design time") knowledge of the REST API's URL structure.



On the user facing web you don't expect to have any knowledge of URL structures. Instead you follow links, do searches, and let the end server calculate the links for you. This is missing link in many REST APIs: they force the client to completely understand the URL structure in order to use the API. This in turns make the client brittle and will cause it to break the first time REST API changes structure.



So for these reasons I cannot see other solutions than handing resource URLs around as parameters in my website URLs.



What I am trying to, is to point out one of the consequences of consuming a truely RESTful API. Namely that your API consumers cannot work with simple item IDs, but have to pass complete resource URLs around.



/Jørn





    
     

    
    


 



  






      

Hi Keven,

> Generally, you wouldn't hand me your URIs that you got back, but a man-in-the-middle could easily 
> catch those URIs (assuming that person defeated SSL when going over SSL). So how is such a scenario 
> handled.. or should be handled by REST apis?

The method I see most often is to use the security in HTTP and a token system like OAuth. For example:

http://developers.sun.com/identity/reference/techart/restwebservices.html

Mark W.

On Fri, Mar 5, 2010 at 7:28 AM, Mark Wonsil <mark_wonsil@...> wrote:

>
>
> Hi Keven,
>
>
> > Generally, you wouldn't hand me your URIs that you got back, but a
> man-in-the-middle could easily
> > catch those URIs (assuming that person defeated SSL when going over SSL).
> So how is such a scenario
> > handled.. or should be handled by REST apis?
>
> The method I see most often is to use the security in HTTP and a token
> system like OAuth. For example:
>
> http://developers.sun.com/identity/reference/techart/restwebservices.html
>
> Mark W.
>
>
For whichever security scheme you choose, yes you must check authN/authZ on
every single request (no different from any webapp in this respect, although
webapps typically do authN implicitly based on the inclusion of a valid
session id token).  That way, if you give me a URI to one of your orders and
I try to access it with my credentials, I'll get either a 403 (forbidden) or
a 404 (if the server doesn't even want me to know that the URI happens to
reference a valid order, just not one of mine).

Craig

As long as DTOs are used in rendering a representation back to the client, there is no inherent coupling introduced to that client. There's coupling to the representation format, which is the coupling everybody is comfortable with on ReST architectures.

 

Don't throw DTOs with the bath water as they say.
 
> To: andjarnic@...
> CC: craigmcc@...; algermissen1971@...; fgaucho@...; rest-discuss@yahoogroups.com
> From: guilherme.silveira@...
> Date: Mon, 1 Mar 2010 13:44:46 -0300
> Subject: Re: [rest-discuss] Differentiating HTTP-based APIs
> 
> Hello guys
> 
> >Are you saying that the J2EE patterns are no longer applicable in general, or for your specific use case?
> I believe if our client is a REST client, DTO as we used to do does
> not make sense.
> 
> According to an old Roy's post: "A REST API should never have �typed�
> resources that are significant to the client."
> http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
> 
> It goes on as: "Specification authors may use resource types for
> describing server implementation behind the interface, but those types
> must be irrelevant and invisible to the client. The only types that
> are significant to a client are the current representation�s media
> type and standardized relation names."
> 
> A typed resource (as this DTO provides to your client) implies in
> tighter coupling between both sides, the opposite direction of freedom
> that you want.
> 
> 
> 
> > Yes, true.. but if you combine the two models into one, while possible, you are requiring your front tier to know about ejb/back end stuff. An even better example of why you would avoid this.. if you were going to use those same XSD generated JAXB classes in a Jersey client (or java client).. and you have the ejb entity annotations in them as well, your client side now has to have the ejb classes to compile.
> 
> You are right.. that's why you should not do that. But that is not
> what I meant, I probably did not leave it clear enough. Session beans
> implies tight coupling by nature: it requires your clients to know and
> share the same interface that your server knows, the opposite
> direction that REST goes, instead of relation names and media types,
> you are using java interfaces and classes. Taking out session beans
> and adding rest in its place:
> 
> (dto) dto s-bean e-bean
> CLIENT ---> WEB TIER --> APP TIER --> DB TIER
> 
> becomes:
> 
> (independent model) resource from here on...
> CLIENT --> WEB TIER -->
> APP TIER --> DB TIER
> 
> What I meant is that it should be your frameworks' responsability to
> map the resource representation to your model... while it does not, so
> one requires dtos, going back to non-restful architectures.
> 
> DTOs are also typically anemic, and because Java classes are closed
> (unlike ruby ones), the client will have to live with an anemic DTO
> representation of his resource.
> 
> That's why I believe DTO and REST should not be together...
> 
> Regards
> 
> Guilherme Silveira
> Caelum | Ensino e Inova��o
> http://www.caelum.com.br/
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 
 		 	   		  
_________________________________________________________________
Tell us your greatest, weirdest and funniest Hotmail stories
http://clk.atdmt.com/UKM/go/195013117/direct/01/

Hey guys,
I do realize you authenticate every request, you taught me that Craig. ;) What I meant is, do I ALSO look at the /orders/<id> (id value) and compare it to the auth header id to make sure it too is valid? If for example Craig and I can both authenticate to the same service, and I give Craig my /orders/<id> (with my auth ID), when Craig tries to make the call to say, delete the order, his authentication will pass the Auth check to be able to access the method/API call, but as far as I can tell, the service would also need to check the /orders/<id> to make sure it matches the authenticated users id.
In order for Craig to delete my order, I would have to have given him some special token the service looks at and knows that he is allowed to delete my order on my behalf. I think OAuth calls this a 3-legged auth. So, my question, to reiterate is HOW does a service, without a 3-legged auth, know if Craig or I am actually deleting my order without checking that the ID passed in the URI matches the ID of the user making the call? OR, more to the point of my question, should EVERY API call not only authenticate a user, but validate that for a given call if an ID is passed in the URI that it matches the authenticated user's id. I think I repeated myself. :D

--- On Fri, 3/5/10, Craig McClanahan <craigmcc@...> wrote:

From: Craig McClanahan <craigmcc@...>
Subject: Re: [rest-discuss] Re: Thoughts about URLs for a REST driven website
To: "Mark Wonsil" <wonsil@...m>
Cc: "Kevin Duffey" <andjarnic@...>, rest-discuss@yahoogroups.com, "Jorn Wildt" <jw@...>
Date: Friday, March 5, 2010, 8:48 AM















 
 



  


    
      
      
      On Fri, Mar 5, 2010 at 7:28 AM, Mark Wonsil <mark_wonsil@ yahoo.com> wrote:
















 



  


    
      
      
      Hi Keven,



> Generally, you wouldn't hand me your URIs that you got back, but a man-in-the-middle could easily 

> catch those URIs (assuming that person defeated SSL when going over SSL). So how is such a scenario 

> handled.. or should be handled by REST apis?



The method I see most often is to use the security in HTTP and a token system like OAuth. For example:



http://developers. sun.com/identity /reference/ techart/restwebs ervices.html



Mark W.



For whichever security scheme you choose, yes you must check authN/authZ on every single request (no different from any webapp in this respect, although webapps typically do authN implicitly based on the inclusion of a valid session id token).  That way, if you give me a URI to one of your orders and I try to access it with my credentials, I'll get either a 403 (forbidden) or a 404 (if the server doesn't even want me to know that the URI happens to reference a valid order, just not one of mine).


Craig




    
     

    
    


 



  











      

It sounds like you are asking about how to handle authorization (not
authentication). If so, that's not really a REST issue, but an
implementation detail for HTTP apps.

In my HTTP applications I refer to a list of URIs (or regexp-based URI
templates) plus a list of HTTP methods for each authenticated user; storage
and representation can vary to taste. Consider a user-centered
representation of an application's access control list for a user:

<user id="mamund">
  <acl href="/(.*)" methods="GET,HEAD,OPTIONS" /> <!-- default access -->
  <acl href="/admin/(.*)" methods="!"/> <!-- deny all methods -->
  <acl href="/mamund/(.*)" methods="*"/> <!-- allow all methods -->
</user>

All that is left is to compare the incoming request's METHOD + URI against
the above list. Any access failures result in a "403 Forbidden" response.

Another possible (non HTTP-centric) public ontology for access control can
be found here:
http://dig.csail.mit.edu/2009/Papers/ISWC/rdf-access-control/paper.pdf

mca
http://amundsen.com/blog/



On Fri, Mar 5, 2010 at 20:09, Kevin Duffey <andjarnic@...> wrote:

>
>
> Hey guys,
>
> I do realize you authenticate every request, you taught me that Craig. ;)
> What I meant is, do I ALSO look at the /orders/<id> (id value) and compare
> it to the auth header id to make sure it too is valid? If for example Craig
> and I can both authenticate to the same service, and I give Craig my
> /orders/<id> (with my auth ID), when Craig tries to make the call to say,
> delete the order, his authentication will pass the Auth check to be able to
> access the method/API call, but as far as I can tell, the service would also
> need to check the /orders/<id> to make sure it matches the authenticated
> users id.
>
> In order for Craig to delete my order, I would have to have given him some
> special token the service looks at and knows that he is allowed to delete my
> order on my behalf. I think OAuth calls this a 3-legged auth. So, my
> question, to reiterate is HOW does a service, without a 3-legged auth, know
> if Craig or I am actually deleting my order without checking that the ID
> passed in the URI matches the ID of the user making the call? OR, more to
> the point of my question, should EVERY API call not only authenticate a
> user, but validate that for a given call if an ID is passed in the URI that
> it matches the authenticated user's id. I think I repeated myself. :D
>
>
> --- On *Fri, 3/5/10, Craig McClanahan <craigmcc@...>* wrote:
>
>
> From: Craig McClanahan <craigmcc@...>
> Subject: Re: [rest-discuss] Re: Thoughts about URLs for a REST driven
> website
> To: "Mark Wonsil" <wonsil@...>
> Cc: "Kevin Duffey" <andjarnic@...>, rest-discuss@yahoogroups.com,
> "Jorn Wildt" <jw@...>
> Date: Friday, March 5, 2010, 8:48 AM
>
>
>
> On Fri, Mar 5, 2010 at 7:28 AM, Mark Wonsil <mark_wonsil@ yahoo.com<http://mc/compose?to=mark_wonsil@...>
> > wrote:
>
>>
>>
>> Hi Keven,
>>
>>
>> > Generally, you wouldn't hand me your URIs that you got back, but a
>> man-in-the-middle could easily
>> > catch those URIs (assuming that person defeated SSL when going over
>> SSL). So how is such a scenario
>> > handled.. or should be handled by REST apis?
>>
>> The method I see most often is to use the security in HTTP and a token
>> system like OAuth. For example:
>>
>> http://developers. sun.com/identity /reference/ techart/restwebs
>> ervices.html<http://developers.sun.com/identity/reference/techart/restwebservices.html>
>>
>> Mark W.
>>
>>
> For whichever security scheme you choose, yes you must check authN/authZ on
> every single request (no different from any webapp in this respect, although
> webapps typically do authN implicitly based on the inclusion of a valid
> session id token).  That way, if you give me a URI to one of your orders and
> I try to access it with my credentials, I'll get either a 403 (forbidden) or
> a 404 (if the server doesn't even want me to know that the URI happens to
> reference a valid order, just not one of mine).
>
> Craig
>
>
>
>
> 
>

On Fri, Mar 5, 2010 at 6:04 PM, mike amundsen <mamund@...> wrote:

>
>
> It sounds like you are asking about how to handle authorization (not
> authentication). If so, that's not really a REST issue, but an
> implementation detail for HTTP apps.
>
> In my HTTP applications I refer to a list of URIs (or regexp-based URI
> templates) plus a list of HTTP methods for each authenticated user; storage
> and representation can vary to taste. Consider a user-centered
> representation of an application's access control list for a user:
>
> <user id="mamund">
>   <acl href="/(.*)" methods="GET,HEAD,OPTIONS" /> <!-- default access -->
>   <acl href="/admin/(.*)" methods="!"/> <!-- deny all methods -->
>   <acl href="/mamund/(.*)" methods="*"/> <!-- allow all methods -->
> </user>
>
> All that is left is to compare the incoming request's METHOD + URI against
> the above list. Any access failures result in a "403 Forbidden" response.
>
> This approach works if a URL template is either valid or not for a
particular user, but that doesn't cover Kevin's use case where
"/orders/{id}" is valid for both of us, but we should not be able to see
each other's orders.

As you mentioned, this is not a REST issue at all, because exactly the same
scenario applies to a traditional webapp where a crafty user might try to
hand modify the URL that displays an order's content, plugging in someone
else's orderid to see if the system will let him see it.  A properly
designed webapp should not; neither should a web service.

There's lots of ways to implement this in the back end.  At Jive, for
example, we have a low level DAO that handles the database calls with no
authorization (could be JPA or Hibernate or whatever), and a higher level
"manager" that checks whether the authenticated user has access to the the
requested data.  This is what all of the other business logic in the
application calls -- the DAO is *only* used by the corresponding manager.

The rules for determining authorized access are necessarily domain specific,
but for the use case being described it's pretty simple -- if the
authenticated user owns the requested order, the data should be returned;
otherwise it should not.

And you should use exactly the same logic behind a REST service and a
corresponding webapp that supports HTML based access to the same data.

Craig

PS:  Kevin, if you're really willing to give me your security token and your
identity, as well as the URL for your order, give me a second to set up a
little HTML form so you can give me your banking login credentials too :-).

<snip>
> This approach works if a URL template is either valid or not for a
> particular user, but that doesn't cover Kevin's use case where
> "/orders/{id}" is valid for both of us, but we should not be able to see
> each other's orders.
</snip>

There are lots of possibilities:
detailed list
<user id="kevin">
��<acl href="/orders/1" methods="*"/>
��<acl href="/orders/6" methods="*"/>
��<acl href="/orders/7" methods="*"/>
��<acl href="/orders/8" methods="*"/>
</user>

template:
<user id="craig">
��<acl href="/orders/(2|3|4|5)" methods="*"/>
</user>

change URI design:
order resource URI contains prefix (mca-001, mca-002, etc)
<user id="mamund">
  <acl href="/orders/mca-(.*)" methods="*" />
</user>

etc.

mca
http://amundsen.com/blog/




On Fri, Mar 5, 2010 at 22:44, Craig McClanahan <craigmcc@...> wrote:
>
>
> On Fri, Mar 5, 2010 at 6:04 PM, mike amundsen <mamund@...> wrote:
>>
>>
>>
>> It sounds like you are asking about how to handle authorization (not
>> authentication). If so, that's not really a REST issue, but an
>> implementation detail for HTTP apps.
>>
>> In my HTTP applications I refer to a list of URIs (or regexp-based URI
>> templates) plus a list of HTTP methods for each authenticated user; storage
>> and representation can vary to taste. Consider a user-centered
>> representation of an application's access control list for a user:
>> <user id="mamund">
>> ��<acl href="/(.*)" methods="GET,HEAD,OPTIONS" /> <!-- default access -->
>> ��<acl href="/admin/(.*)" methods="!"/> <!-- deny all methods -->
>> ��<acl href="/mamund/(.*)" methods="*"/> <!-- allow all methods -->
>> </user>
>> All that is left is to compare the incoming request's METHOD + URI against
>> the above list. Any access�failures result in a "403 Forbidden" response.
>
> This approach works if a URL template is either valid or not for a
> particular user, but that doesn't cover Kevin's use case where
> "/orders/{id}" is valid for both of us, but we should not be able to see
> each other's orders.
>
> As you mentioned, this is not a REST issue at all, because exactly the same
> scenario applies to a traditional webapp where a crafty user might try to
> hand modify the URL that displays an order's content, plugging in someone
> else's orderid to see if the system will let him see it.� A properly
> designed webapp should not; neither should a web service.
>
> There's lots of ways to implement this in the back end.� At Jive, for
> example, we have a low level DAO that handles the database calls with no
> authorization (could be JPA or Hibernate or whatever), and a higher level
> "manager" that checks whether the authenticated user has access to the the
> requested data.� This is what all of the other business logic in the
> application calls -- the DAO is *only* used by the corresponding manager.
>
> The rules for determining�authorized access�are necessarily domain specific,
> but for the use case being described it's pretty simple -- if the
> authenticated user owns the requested order, the data should be returned;
> otherwise it should not.
>
> And you�should use exactly the same logic behind a REST service and a
> corresponding webapp that supports HTML based access to the same data.
>
> Craig
>
> PS:� Kevin, if you're really willing to give me your security token and your
> identity, as well as the URL for your order, give me a second to set up a
> little HTML form so you can give me your banking login credentials too :-).
>

I suppose what I am asking is, on every request, I basically have to perform some ACL on the given URL id and the authorization header id to make sure they match. IF they do (and the id is allowed to make the call via acl), then it continues. But, there is ALWAYS some logic in place to check this. Right now, for example, I simply use the Auth header to validate, if so, the call continues. In my current way of doing this, it's very possible someone could give someone else (or someone could steal it) the URL and anyone that authenticates, has access to it. 

So basically I should probably first make sure the calling user via the Authorization header is valid. Then, make sure that matches up to the URL id (if one is applicable), and then make sure the id has the rights to access the method being requested. If all that goes thru, then the method can take place. That about right?


Craig, you wouldn't find much if you had access to my account. It's pretty empty sadly! 

--- On Fri, 3/5/10, mike amundsen <mamund@...> wrote:

From: mike amundsen <mamund@...>
Subject: Re: [rest-discuss] Re: Thoughts about URLs for a REST driven website
To: craigmcc@...
Cc: rest-discuss@yahoogroups.com
Date: Friday, March 5, 2010, 8:23 PM







 



  


    
      
      
      <snip>

> This approach works if a URL template is either valid or not for a

> particular user, but that doesn't cover Kevin's use case where

> "/orders/{id} " is valid for both of us, but we should not be able to see

> each other's orders.

</snip>



There are lots of possibilities:

detailed list

<user id="kevin">

  <acl href="/orders/ 1" methods="*"/ >

  <acl href="/orders/ 6" methods="*"/ >

  <acl href="/orders/ 7" methods="*"/ >

  <acl href="/orders/ 8" methods="*"/ >

</user>



template:

<user id="craig">

  <acl href="/orders/ (2|3|4|5) " methods="*"/ >

</user>



change URI design:

order resource URI contains prefix (mca-001, mca-002, etc)

<user id="mamund">

  <acl href="/orders/ mca-(.*)" methods="*" />

</user>



etc.



mca

http://amundsen. com/blog/



On Fri, Mar 5, 2010 at 22:44, Craig McClanahan <craigmcc@gmail. com> wrote:

>

>

> On Fri, Mar 5, 2010 at 6:04 PM, mike amundsen <mamund@yahoo. com> wrote:

>>

>>

>>

>> It sounds like you are asking about how to handle authorization (not

>> authentication) . If so, that's not really a REST issue, but an

>> implementation detail for HTTP apps.

>>

>> In my HTTP applications I refer to a list of URIs (or regexp-based URI

>> templates) plus a list of HTTP methods for each authenticated user; storage

>> and representation can vary to taste. Consider a user-centered

>> representation of an application' s access control list for a user:

>> <user id="mamund">

>>   <acl href="/(.*)" methods="GET, HEAD,OPTIONS" /> <!-- default access -->

>>   <acl href="/admin/ (.*)" methods="!"/ > <!-- deny all methods -->

>>   <acl href="/mamund/ (.*)" methods="*"/ > <!-- allow all methods -->

>> </user>

>> All that is left is to compare the incoming request's METHOD + URI against

>> the above list. Any access failures result in a "403 Forbidden" response.

>

> This approach works if a URL template is either valid or not for a

> particular user, but that doesn't cover Kevin's use case where

> "/orders/{id} " is valid for both of us, but we should not be able to see

> each other's orders.

>

> As you mentioned, this is not a REST issue at all, because exactly the same

> scenario applies to a traditional webapp where a crafty user might try to

> hand modify the URL that displays an order's content, plugging in someone

> else's orderid to see if the system will let him see it.  A properly

> designed webapp should not; neither should a web service.

>

> There's lots of ways to implement this in the back end.  At Jive, for

> example, we have a low level DAO that handles the database calls with no

> authorization (could be JPA or Hibernate or whatever), and a higher level

> "manager" that checks whether the authenticated user has access to the the

> requested data.  This is what all of the other business logic in the

> application calls -- the DAO is *only* used by the corresponding manager.

>

> The rules for determining authoriz ed access are necessarily domain specific,

> but for the use case being described it's pretty simple -- if the

> authenticated user owns the requested order, the data should be returned;

> otherwise it should not.

>

> And you should use exactly the same logic behind a REST service and a

> corresponding webapp that supports HTML based access to the same data.

>

> Craig

>

> PS:  Kevin, if you're really willing to give me your security token and your

> identity, as well as the URL for your order, give me a second to set up a

> little HTML form so you can give me your banking login credentials too :-).

>



    
     

    
    


 



  






      

On Fri, Mar 5, 2010 at 11:02 PM, Kevin Duffey <andjarnic@...> wrote:

> I suppose what I am asking is, on every request, I basically have to
> perform some ACL on the given URL id and the authorization header id to make
> sure they match. IF they do (and the id is allowed to make the call via
> acl), then it continues. But, there is ALWAYS some logic in place to check
> this. Right now, for example, I simply use the Auth header to validate, if
> so, the call continues. In my current way of doing this, it's very possible
> someone could give someone else (or someone could steal it) the URL and
> anyone that authenticates, has access to it.
>
> So basically I should probably first make sure the calling user via the
> Authorization header is valid. Then, make sure that matches up to the URL id
> (if one is applicable), and then make sure the id has the rights to access
> the method being requested. If all that goes thru, then the method can take
> place. That about right?
>

Sounds good, as long as "matches up to the URL id" means "is authorized to
perform the request specified by the verb and URI that was submitted".
First make sure the user is properly authenticated (send 401 if not).  Then,
ensure that the authenticated user is allowed to perform the request they
are attempting (send 403 or 404 if not).  The rules for "allowed to perform"
are specific to the application -- in the use case we've been describing,
you could enforce a rule (for example) that the creator of an order can do
anything, but an administrative username (for producing reports) can only do
a GET.

For Jersey in particular, check out the @RolesAllowed annotation, which you
can couple with a security filter to perform this kind of check pretty
easily.  The security filter can, for example, examine the path of the
request (so it could figure out which order you're trying to access) and
grant you the "owner" role only if you are indeed the owner of that order.
Then, putting "@RolesAllowed("owner")" on a resource method is sufficient to
trigger the 403 if you don't have the specified role.

>
>
> Craig, you wouldn't find much if you had access to my account. It's pretty
> empty sadly!
>
> :-)

Craig

Take a look at the links in this post: 
http://tech.groups.yahoo.com/group/rest-discuss/message/14971

/Jørn

----- Original Message ----- 
From: "Kevin Duffey" <andjarnic@...>
To: <rest-discuss@yahoogroups.com>; "Jorn Wildt" <jw@...>
Sent: Friday, March 05, 2010 4:14 PM
Subject: Re: [rest-discuss] Re: Thoughts about URLs for a REST driven 
website


Hi,

If I understand HATEOAS correctly, if I make a /orders call, get back a list 
of orders with links on what I can do next, the server at this point has no 
"state" memory.. it has no idea after it sent back the response, that it 
just told me "here is what you can do now". I could come back 3 years later, 
and use those URIs it sent back to me and it should work. Is that not 
correct?

As for giving it to someone else, well, they would first have to pass 
authentication as far as I know. But that does raise an interesting 
question. Using your example, how would the RESTful api "prevent" any call 
being made from anyone if they authenticate? That is, if you and I are both 
authenticated users, and you pull a /orders with your info, and it gives you 
a list back for your orders, you could then give me the URIs it returns, and 
I could make those same calls on your behalf, using my authentication. 
Correct? My only guess is that every single call made to a RESTful API 
should perform validation checks which would be expensive I suppose if every 
time I tried to call one of your URIs for a specific order, the RESTful api 
had to verify that the user making the call is the same user that received 
the URIs in the first place. I am not sure if that makes sense, rereading 
it, but I am curious how this sort of issue is prevented. Generally, you
 wouldn't hand me your URIs that you got back, but a man-in-the-middle could 
easily catch those URIs (assuming that person defeated SSL when going over 
SSL). So how is such a scenario handled.. or should be handled by REST apis?



Consider this situation: your are surfing the web and a friend of yours 
comes by with an Amazon order ID. "Could you please check this order for 
me?" he says. "Sure!" you answer. Now what do you do? I am quite sure that 
you are not going to type the direct Amazon order url into your browser - 
how would you know what it should look like? But this is equivalent to your 
suggested REST API consumer - when you pass it an order ID, it utilizes it's 
apriori ("at design time") knowledge of the REST API's URL structure.



On the user facing web you don't expect to have any knowledge of URL 
structures. Instead you follow links, do searches, and let the end server 
calculate the links for you. This is missing link in many REST APIs: they 
force the client to completely understand the URL structure in order to use 
the API. This in turns make the client brittle and will cause it to break 
the first time REST API changes structure.



So for these reasons I cannot see other solutions than handing resource URLs 
around as parameters in my website URLs.



What I am trying to, is to point out one of the consequences of consuming a 
truely RESTful API. Namely that your API consumers cannot work with simple 
item IDs, but have to pass complete resource URLs around.



/Jørn









    

"Jorn Wildt" wrote:
>
> Thanks for taking your time to discuss this.
> 
> I'll dive right into this statement:
> 
> > http://charger.bisonsystems.net/date?iso=2010-03-04 simply loads:
> > http://en.wiski.org/date?iso=2010-03-04 while adding some headers.
> 
> Now, how does your server know how to transform the incoming
> http://charger.bisonsystems.net/date?iso=2010-03-04 request to the
> http://en.wiski.org/date?iso=2010-03-04 location?
> 

Because that's how I've coded the resource to behave.  The /date
resource on charger has both client and server connectors.  Its client
connector is programmed to proxy responses from a remote server.  It
would not matter if this back-end interaction weren't RESTful, what
matters is that the front-end is RESTful from the viewpoint of my end-
user application.

>
> You can only do this by having some knowledge of your backend REST
> API, namely that the URL template is
> http://en.wiski.org/date?iso={date}. If you did not have this
> information, how would you then know what to do with the "2010-03-04"
> value?
> 

So?

I'm sincerely trying to help, here.  You're obviously misunderstanding
something, I'm trying to figure out what, exactly.  I think, perhaps,
you're misinterpreting Roy's comment, "A REST API should be entered
with no prior knowledge beyond the initial URI (bookmark)...".

This applies to the client's interaction with the system.  In my /date
service, the "application" in the REST sense is to return metadata
corresponding to the given ISO 8601 data string.  In my demo, the client
application sends this translation request to charger.bisonsystems.net,
and the response appears to come from charger.bisonsystems.net.

The client application has no knowledge of en.wiski.org, nor does it
need any.  The interaction between charger.bisonsystems.net and en.
wiski.org is out-of-scope to the REST application.  The user's agent
does not "enter" the back-end API, so the mapping between charger and
en does not constitute prior knowledge of the API.  The API for en.
wiski.org isn't part of my system, only the API on charger.
bisonsystems.net.

> 
> Lets see what should be in the search result. Links! Certainly, but
> links to what? It cannot return links to the www site since that
> would imply my REST API knew something about it's client. So it must
> return links to REST API resources. This mean we would get the REST
> API URL http://rest.mysite.com/feeds/peter back.
> 

Links to the available state transitions.  Your XHTML representations
link to XHTML representations.  Your Atom representations link to Atom
representations.  Each XHTML representation has a link rel='alternate'
pointing to its equivalent in Atom, and vice-versa.

Where in REST are you getting the notion that your API can't know
anything about the client?  The whole premise of content negotiation is
that your API can tailor its response based on client capability.

>
> Now, what should my www site do with the
> http://rest.mysite.com/feeds/peter URL in order to generate a browser
> link to itself that can display the feed?
>

If the requesting client is Atom, then the 200 response includes a link
rel='alternate' to the equivalent URI on the frontend.  If the
requesting client needs XHTML, then 301-redirect to that equivalent URI
on the frontend.

>
> My www site knows nothing
> about the URL format, so I has no way to figure out how to select
> "peter" and present a http://www.mysite.com/blogs/peter URL to the
> end user.
>

I can't conceive of any reason why a frontend would be coded without
knowledge of the backend it's proxying.  All we're talking here is a
redirect of /blogs/{user} to /feeds/{user} on a different domain, and
vice-versa depending on media type.  When the media type matches, it's
an internal redirect, if not it's a 301.  Simple!

Setting up URL rewriting is a common practice.  All it is, is mapping
one URI allocation scheme to another.  There is no REST constraint
enjoining this behavior.

>
> And here is my point: the only thing the www site can do,
> is to include the full REST URL in the www URL.
> 

If your assumptions were correct, then I'd agree.  But, if you're
arriving at the conclusion that REST is somehow requiring you to do
this, then your assumptions must not be correct.  I assure you, there
is no such constraint in REST.  The ones that are there are hard enough
to get right, I strongly suggest not imagining others.  ;-)

>
> You could argue that the REST search should return both the complete
> resource URL as well as the feed name "peter".
>

No, I would never make such an argument.  It doesn't matter whether the
search is done against the frontend or the backend, or the results are
in XHTML or Atom -- the response will contain a link rel='alternate'
that user-agents can follow to the correct variant, if needed.

If a resource has two variants with unique URLs, just link them together
using rel='alternate' or 'source' or 'feed'.  There is no need for both
URLs to be present in a search result in order for the resource to be
'discovered' and has nothing to do with the hypertext constraint.

>
> But then, again, the
> www site would have to know how to transform "peter" into the REST
> API URL http://rest.mysite.com/feeds/peter.
> 

Of course.  Again, so?  REST is a layered architecture.  A client
interacts with your front-end, it cannot "see" farther than that.  Your
front-end resource knows how to map that request onto the back-end
system, but this interaction should be opaque to the client.

Requiring the client to know the back-end URI in order to formulate a
request to the front-end results in a coupling which breaks the
layered-system constraint.  The back-end URI allocation scheme can't be
changed without re-coding at least the front-end, if not the clients.

Whereas, in a decoupled system, the back-end URI allocation can change
and the front-end only needs to be reconfigured.  The front-end would
not need to be re-coded to instruct clients of the new back-end URI
scheme (since the clients don't need to know about it), so clients would
just continue interacting with the front-end as before.

In the case of the /date service, everything about it could be changed.
I could move it to a different domain, or I could change the syntax of
the query.  Or both.  In which case, I would just change the mapping on
charger to reflect the modifications.

Now, imagine the mess updating the /date backend would cause, if all
requests looked something like this:

http://charger.bisonsystems.net/date?url=http://en.wiski.org/date?iso=

See how, by trying to pass the back-end URIs around inside the front-end
URIs, the system becomes coupled due to the requirement that the client
must "see" beyond the server it's interacting with.  REST is quite
powerful in that it abstracts away any need for this sort of coupling.
I promise there's no RESTly reason for embedding back-end URLs in front-
end requests.

The fact that you've come up with a solution that's the opposite of REST
tells me that there's a fundamental error in your understanding of REST.
I don't mean to condescend or discourage, I'd just like to help isolate
that error and see if we can't get you straightened out.

-Eric

Thanks again for a thorough answer. I'll do my best to formulate what I 
think. Apparently it's not that easy :-)

> Of course.  Again, so?  REST is a layered architecture.  A client
> interacts with your front-end, it cannot "see" farther than that.  Your
> front-end resource knows how to map that request onto the back-end
> system, but this interaction should be opaque to the client.

Yes! It should be opaque to the client. Certainly. One more reason not to 
pass the complete URL back to the client. We certainly agree on that (it's 
not that I want to pass the full resource URL, quite the opposite, I am just 
trying to figure out how to avoid it in the most RESTful way).

> You're obviously misunderstanding
> something, I'm trying to figure out what, exactly.  I think, perhaps,
> you're misinterpreting Roy's comment, "A REST API should be entered
> with no prior knowledge beyond the initial URI (bookmark)...".

Yes, this is the constraint I am working with.

> This applies to the client's interaction with the system.

Yes. But in this setup we have two clients. One client is our front-end 
consuming the back-end API. Another client is the web-browser consuming our 
front-end. Both consumers should behave RESTful and have as little apriori 
knowledge as possible of the REST system it consumes.

> Whereas, in a decoupled system, the back-end URI allocation can change
> and the front-end only needs to be reconfigured.

Stop. You said "front-end needs to be reconfigured". This means you have a 
static coupling between your front-end and your backend REST API. This is 
what I am trying to avoid. Everybody says "Thou shall not have static 
couplings to the REST API you consume".

By passing the complete resource URLs around I can modify my backend 
structure as much as I want, and I'll never have to configure or recode 
anything in the front-end.

> Now, imagine the mess updating the /date backend would cause, if all
> requests looked something like this:
>
> http://charger.bisonsystems.net/date?url=http://en.wiski.org/date?iso=
>
> See how, by trying to pass the back-end URIs around inside the front-end
> URIs, the system becomes coupled due to the requirement that the client
> must "see" beyond the server it's interacting with

But URLs are opaque - right? The client, a web-browser, can ignore anything 
thats contained in "?url=...". The stuff in the dots is just an opqaue 
identifier to the client. It could be anything. The fact that it is a URL is 
irrelevant to the client. Some blogging system even has complete URLs as 
their ATOM identifiers.

Lets assume the user makes a search for "peter" on our front-end. This in 
turns makes the front-end forward the keyword "peter" to a published search 
URL in the REST API. The REST API then returns an ATOM entry like below, 
telling the REST API consumer (our front-end) where it can find the 
resource:

  <entry>
    <link rel="self" href="http://rest.mysite.com/feeds/peter"/>
  </entry>

REST is all about hypermedia and following links. So the REST consumer, our 
front-end, should not care about the content of the URL. It should just 
accept that URL as a resource reference and use it as such.

If our front-end was a .NET/Java application it would then keep that URL in 
memory while it presented a selection list to the end-user. When the 
end-user selected the "link", it would lookup the selection index, find the 
resource URL, fetch it, and present peter's ATOM content to the end-user.

But unfortunately our client is a website and we want to present a single 
URL for the end-user to click. A URL which would direct the end-user to a 
page that loads the found resource, formats it using HTML, and return that 
HTML to the end-user. How would that link look? Well, it would have to 
contain the whole resource reference (and I can already here you scream 
"noooo!", but read on).

But, yes, I am totaly aware that the ATOM entry also contains an identifier:

  <entry>
    <id>peter</id>
    <link rel="self" href="http://rest.mysite.com/feeds/peter"/>
  </entry>

Now, my front-end can decide to get the ID, use it's apriori knowledge of 
the back-end URL format, and convert it to the complete URL when needed. But 
from a RESTful point of view, what is best - to let the front-end construct 
the URL based on some configuration of how the REST API behaves, or to just 
follow the link that the back-end server has created for us?

> Where in REST are you getting the notion that your API can't know
> anything about the client?
> ...
> Each XHTML representation has a link rel='alternate'

Lets take another example. I want to make a website that shows Flickr 
albums. I let my user enter search keywords on my website, forward that to 
Flickr, parse the search result, and present it to my end user. Lets also 
assume Flickr uses ATOM for the search result. Now, would Flickr have any 
way to generate an "alternate" link for me? No, certainly not. So again I 
can only take Flickr's complete album resource URL and put that into the 
link for my "show_this_ Flickr album" webpage in my system.

But I actually got one solution suggested by Sebastian from Open Rasta. See 
http://groups.google.com/group/openrasta/browse_thread/thread/f5994b6c7ce231b6

To avoid the static coupling we need a way for the REST API to announce it's 
URL formats at runtime. This can be done using HTML forms. Now the front-end 
can lookup the search form for blogs, decode it, and conclude that the blog 
URL format is http://rest.mybackend.com/feeds?blogname={xxx} where "xxx" is 
a query parameter defined with an <input name="blogname"/> element.

Thanks for reading all this through.

/J�rn

I just heard the news that Felipe Gaucho, one of the most active members on
this list, passed away yesterday.

Terrible and shocking news this is. May he rest in peace...

http://weblogs.java.net/blog/claudio/archive/2010/03/06/felipe-gaucho-we-will-miss-you

http://www.cejug.org/2010/03/06/noticia-triste-para-o-java-no-brasil-e-o-ceara/

http://www.devoxx.com/display/DV09/Home

J�rn Wildt wrote:
> 
> > You're obviously misunderstanding
> > something, I'm trying to figure out what, exactly.  I think,
> > perhaps, you're misinterpreting Roy's comment, "A REST API should
> > be entered with no prior knowledge beyond the initial URI
> > (bookmark)...".
> 
> Yes, this is the constraint I am working with.
> 
> > This applies to the client's interaction with the system.
> 
> Yes. But in this setup we have two clients. One client is our
> front-end consuming the back-end API. Another client is the
> web-browser consuming our front-end. Both consumers should behave
> RESTful and have as little apriori knowledge as possible of the REST
> system it consumes.
> 

OK, I can see where you're going wrong.

>
> > Whereas, in a decoupled system, the back-end URI allocation can
> > change and the front-end only needs to be reconfigured.
> 
> Stop. You said "front-end needs to be reconfigured". This means you
> have a static coupling between your front-end and your backend REST
> API. This is what I am trying to avoid. Everybody says "Thou shall
> not have static couplings to the REST API you consume".
> 

I'm not interested in what everybody says; everybody gets REST wrong.
I'm interested in what Roy says, which in this case would be along the
lines of, "REST doesn't eliminate the need for a clue."  The wiski.org
/date service will eventually have an Xforms interface to describe the
API -- a URI template won't do, because the number of days in February
is algorithmic.  But, that doesn't mean a client of the API is required
to be an Xforms client, or otherwise consume that form.

The client connector of my proxy component (charger) isn't required to
code itself, nor is it required to be some sort of AI driving a
hypertext form.  Just as a Web page requires a user to make a choice.
All I need to know to write a simple proxy, is {YYYY-MM-DD}.  My proxy
isn't required to discover that URI template by itself.  It's still a
REST client, and hypertext is still the engine of application state.

REST is interested in the communication between charger and wiski.org,
and from the perspective of the protocol going across the wire, how
charger knows what resource to request from wiski.org remains opaque
behind the interface.  The communication meets every REST constraint, I
assure you.

> 
> > Now, imagine the mess updating the /date backend would cause, if all
> > requests looked something like this:
> >
> > http://charger.bisonsystems.net/date?url=http://en.wiski.org/date?iso=
> >
> > See how, by trying to pass the back-end URIs around inside the
> > front-end URIs, the system becomes coupled due to the requirement
> > that the client must "see" beyond the server it's interacting with
> 
> But URLs are opaque - right? The client, a web-browser, can ignore
> anything thats contained in "?url=...". The stuff in the dots is just
> an opqaue identifier to the client. It could be anything. The fact
> that it is a URL is irrelevant to the client. Some blogging system
> even has complete URLs as their ATOM identifiers.
> 

How does the client, making a request to charger, know the URI for
en.wiski.org?  If it's getting this URI from wiski.org, then asking
charger to translate it, then the layered-system constraint is broken
and the system is coupled rather tightly.

If the client knows the en.wiski.org URI because charger told it so,
then charger obviously already knows wiski.org's API.  For charger to
pass this on to the client, would be to induce the coupling incurred by
breaking the layered-system constraint.

Regardless of how the client is instructed of this URI-within-a-URI,
all bookmarks to charger break if wiski.org changes its URI template,
right?  Different naming authorities -- why make charger responsible
for changes to wiski.org?  You'd have to 301-redirect all old charger
URIs to their current equivalents, as well as have charger start
minting new URIs reflecting wiski.org's new URI template.

Please tell me you see how this is coupling, and a bad thing.  If
charger obeys the layered-system constraint, as it does now, then none
of the URIs minted by charger in the past break, if wiski.org changes
its URI template.  The client is only interacting with charger, so
charger shouldn't be exposing the URIs of another layer.

It doesn't really matter if the frontend or the backend or some other
system is generating those URIs.  If a change to a backend URI format
causes frontend URIs to break, it's rather damning evidence of failure
to apply the layered-system constraint.

Granted, the URIs are opaque to the client, in that the client doesn't
recognize the wiski.org URIs as such, but the URIs still _break_ don't
they?  You can't sidestep this coupling by declaring broken URIs opaque.

No REST constraint is being broken by having charger proxy wiski.org,
this is a common solution to common problems of Web development.  Don't
believe any argument that leads you to conclude that setting up simple
forwarding or proxying of URIs is forbidden by REST.  That just isn't
the case.

-Eric

Okay, so knowing the back-end URL format in the front-end is not unRESTful. Fine, I'll accept that it is not strickly unRESTful according to Roy's constraints. It's just that it is brittle and, as you say yourself, requires re-configuration of the front-end when the back-end changes. It simply anoys me: no one have ever told me to reconfigure my browser in order to lookup an ordernumber at Amazon, just because they changed their internal implementation and URL structure.

> Please tell me you see how this is coupling, and a bad thing.

Yes, the idea of passing the URL to the web-browser is also brittle as you point out, probably even more brittle. I totally agree with that.

So neither solutions are perfect. What can we do instead?

> The wiski.org
> /date service will eventually have an Xforms interface to describe the
> API -- a URI template won't do, because the number of days in February
> is algorithmic.  But, that doesn't mean a client of the API is required
> to be an Xforms client, or otherwise consume that form.

Yes. Publishing search forms in the back-end solves most of the problems. Now my back-end has a way to instruct the front-end how to fetch the ATOM resource referenced externally by the simple string "peter". 

Compare it to my previous Amazon ordernumber example: you, as a web-user, would never type the direct URL to Amazons order-information-page if all you had was an ordernumber. So instead you open the Amazon "search for orders" form and insert your ordernumber. Amazon can then redirect you to whatever internal URL they want.

The same can be done programmatically in the front-end if just the back-end has a machine-readable search form. This adds my required flexibility at the cost of a bit more code in the front-end.

> No REST constraint is being broken by having charger proxy wiski.org,
> this is a common solution to common problems of Web development.  Don't
> believe any argument that leads you to conclude that setting up simple
> forwarding or proxying of URIs is forbidden by REST.  That just isn't
> the case.

Agreed. It does not break any REST principles.


So what I am missing now is a standard format for publishing "these are the ways you should access items using the REST API" - in a way that can be parsed at runtime.

Here is one suggestion:

1) The official "here can you find the specs" kind of REST "sitemap".

A simple microformat. Look for anchors of class "rest.search". Requires only a shared knowledge of the identifiers "mysite-orders" and "mysite-customers".

<html>
  <body>
	<p>... human readable help and introduction ...</p>
    <ul>
	  <li><a href="http://mysite.com/ordersearch.html" class="rest.search" id="mysite-orders">Orders</a></li>
	  <li><a href="..." class="rest.search" id="mysite-customers">Orders</a></li>
    </ul>
  </body>
</html>


2) The "mysite.orders" search specification at http://mysite.com/ordersearch.html

Requires only shared knowledge of the fact that there will be an <input> element with the ID "ordernumber".

<html>
  <body>
    <form id="mysite-orders" action="..." method="..." enctype="...">
	  <input id="ordernumber" name="amazon-internal-ordernumber"/>
	  <input type="submit"
	</form>
  </body>
<html>

All of this information could be auto-generated from a platform like OpenRasta. It should also be easy to create a library that consumes these documents at runtime (and caches them, so we don' have to fetch the search spec eveytime).


/J�rn

Volume 6 of This week in REST is up on the REST wiki -
http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Mar_1_2010
and the blog - http://wp.me/pMXr1-J.

For contributing links this week visit
http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Mar_8_2010

Cheers!
Ivan

"Jorn Wildt" wrote:
>
> Okay, so knowing the back-end URL format in the front-end is not
> unRESTful. Fine, I'll accept that it is not strickly unRESTful
> according to Roy's constraints.
>

Whenever I come across the notion of "Roy's REST" I can't help but
wonder, what other REST is there?  If you have to qualify your REST
implementation as based on something other than Roy's constraints, then
you probably don't have REST.  ;-)

>
> It's just that it is brittle and, as
> you say yourself, requires re-configuration of the front-end when the
> back-end changes. It simply anoys me: no one have ever told me to
> reconfigure my browser in order to lookup an ordernumber at Amazon,
> just because they changed their internal implementation and URL
> structure.
> 

I said reconfigure the frontend, not reconfigure the client, though.
The interaction between charger and wiski.org is hidden from the client,
which is requesting ISO date-string translation from charger.  The
wiski.org backend can change completely without affecting user-agent
interaction with the frontend.  The frontend simply needs a new mapping
to the backend, this has no effect on the client (unless you've embedded
the backend URI in the request to the frontend).

> 
> So neither solutions are perfect. What can we do instead?
> 

I don't see any imperfection there.  I'll humor you, though, and point
out that I could write the /date service proxy on charger to use an
actual URI template from wiski.org.  I could then change the URI
allocation scheme on wiski.org, update its URI template, and the /date
service proxy on charger would automatically use the new URI allocation.

You could do this, if you didn't mind adding complexity to support an
optimization.  I'm just trying to get the point across, that if you do
so you shouldn't point to it and say, "REST made me do it," because this
notion is really neither here nor there as far as REST is concerned.

As with any REST development, I can't stress enough that you should only
apply those REST constraints that bring about a benefit to your project,
while leaving room to add constraints in the future, as the system
scales to a point where they make sense in terms of cost-benefit.  This
applies also, to any additional constraints you may wish to add.

So the question would be, in my case, what benefit would I achieve by
basing the system on a dynamic URI template instead of hard-coding?
The answer, even where REST constraints are involved, must make
pragmatic sense to me -- the answer never comes down to REST dogma,
only quantifiable benefits to the system.  I see none, in fact I see
greater maintenance costs, so I'll let the hard-coding stand.

Your concerns are valid for clients interacting with frontends, but
they don't extend to the communication between layers in a system.  The
wiski.org /date service and charger's /date proxy are both RESTful, even
if the communication between charger and wiski.org isn't hypertext
driven -- the API is, taken as a whole, as are its constituent parts.

I'm perhaps overly-wordy in my explanation, it's just difficult for me
to explain REST nuances to others, which come naturally to me for some
reason... perhaps because I read Roy's thesis through twice each year,
and refer to it regularly when engaged in REST development.

>
> > The wiski.org
> > /date service will eventually have an Xforms interface to describe
> > the API -- a URI template won't do, because the number of days in
> > February is algorithmic.  But, that doesn't mean a client of the
> > API is required to be an Xforms client, or otherwise consume that
> > form.
> 
> Yes. Publishing search forms in the back-end solves most of the
> problems. Now my back-end has a way to instruct the front-end how to
> fetch the ATOM resource referenced externally by the simple string
> "peter". 
> 

Nuance, again.  Your back-end has a hypertext REST API which may be used
to instruct generic user-agents how to interact with it, as well as to
provide a self-documenting API which may be referenced by anyone
developing a client specific to your API.  A client, i.e. the frontend,
doesn't actually have to consume the hypertext -- all REST says is that
the API must provide it.

These are component implementation details, hidden behind the generic
interface, and are thus out-of-scope to REST.  If you insist on applying
some sort of constraint to component implementation, you can, but it
isn't a REST constraint.  So, just as with any REST constraint, you'll
need to evaluate its pros and cons -- except you can't do that by
referring to REST since this constraint isn't in there.

> 
> The same can be done programmatically in the front-end if just the
> back-end has a machine-readable search form. This adds my required
> flexibility at the cost of a bit more code in the front-end.
> 

If this is a real requirement of your system, fine.  If you're doing
this to "score REST points", don't -- there are none to be had.

> 
> So what I am missing now is a standard format for publishing "these
> are the ways you should access items using the REST API" - in a way
> that can be parsed at runtime.
> 

I don't understand.  Hypertext is the engine of application state.  I
refer you again to my demo site.  All XHTML representations link to one
XSLT transformation.  That XSLT transformation instructs the client, at
runtime, how and when to dereference the /date service -- when it
encounters a unique-to-page ISO 8601 date string, the XSLT code calls
this template:

<xsl:template name='date-service'>
 <xsl:param name='iso-date'/>
 <xsl:param name='date' select="document(concat('../../date?iso=',$iso-date))//xht:p"/>
 <xsl:value-of select="concat($date/xht:abbr[1]/@title,', ')"/>
 <xsl:value-of select="concat($date/xht:abbr[2]/@title,' ')"/>
 <xsl:value-of select="concat($date/xht:abbr[3],' ')"/>
 <xsl:value-of select='$date/xht:span'/>
</xsl:template>

I don't know what a "standard format" would be, all I know is that
there are many standard hypertext formats which may be employed to
instruct clients how to use a REST API.  This is but one example, using
standard media types -- charger sends some hypertext (XSLT in this 
case) which describes the use of a simple REST Web service, to replace
one string with another of a specific format.

> 
> 1) The official "here can you find the specs" kind of REST "sitemap".
> 

This is exactly the opposite of what Roy means by, "A REST API should be
entered with no prior knowledge beyond the initial URI."  If, given a
URI for some resource in a system, I must consult some other "sitemap"
resource before I can request another URI in the system, then the API
is being driven by out-of-band knowledge, not hypertext.

While my /date service currently lacks rel='up', that will eventually 
link all representations to the service document, i.e. an Xforms 
interface.  For now, though, regardless of entry point, any client that
groks rel='next' and rel='prev' as Link headers can traverse the entire 
service output.  IOW, the entire service is accessible through each and 
every URI, this doesn't mean each and every URI needs a <form> of some 
sort.  HTH.

-Eric

> Whenever I come across the notion of "Roy's REST" I can't help but
> wonder, what other REST is there?

:^)

>> It's just that it is brittle and, as
>> you say yourself, requires re-configuration of the front-end when the
>> back-end changes.
> ...
> I said reconfigure the frontend, not reconfigure the client, though.

Yes, you won't have to reconfigure the browser client. But this may be one 
of the places where we disagree on what the "client" is. In my head I have a 
picture of a completely open back-end API. Open to the whole world that is. 
Anyone that can access the website can also access the REST API directly 
instead. I want everybody to be able to write different and/or better 
front-ends than I do. This means I don't have control over who consumes my 
back-end. In my scenario I have one REST API and a multitude of clients that 
uses it. One of these happens to be my own website.

> ... use an actual URI template from wiski.org ...
> You could do this, if you didn't mind adding complexity to support an
> optimization.  I'm just trying to get the point across, that if you do
> so you shouldn't point to it and say, "REST made me do it," because this
> notion is really neither here nor there as far as REST is concerned.

Ok.

> As with any REST development, I can't stress enough that you should only
> apply those REST constraints that bring about a benefit to your project,
> while leaving room to add constraints in the future, as the system
> scales to a point where they make sense in terms of cost-benefit.

Yeps. That makes sense. The more flexible solution is certainly more 
expensive. Is it worth it? It depends. In my scenario with many different 
clients I believe it's worth it. I won't be able to tell all my clients that 
URL templates has changed unless I do something similar to the forms 
requirement.

> The answer, even where REST constraints are involved, must make
> pragmatic sense to me -- the answer never comes down to REST dogma,
> only quantifiable benefits to the system.  I see none, in fact I see
> greater maintenance costs, so I'll let the hard-coding stand.

Unfortunately, as a REST novice, I do not have experience enough with REST 
to really tell when it makes sense to use it or not. Well, maybe I do, but 
as newbies we often have to stick to the dogma since that is all we have. We 
don't have the experience and understanding that tells us that a specific 
part of REST can be left out or must be respected.

So it often comes down to dogma due to uncertainty of what will happen if we 
don't do everything stricly by the book. In this cases my starting point 
was - what benefits do I loose or gain if don't shuffle the full resource 
URLs around. I think I got that covered now :-)

>> 1) The official "here can you find the specs" kind of REST "sitemap".
>
> This is exactly the opposite of what Roy means by, "A REST API should be
> entered with no prior knowledge beyond the initial URI."

Then I am lost again :-(

> If, given a URI for some resource in a system, I must consult some other 
> "sitemap"
> resource before I can request another URI in the system, then the API
> is being driven by out-of-band knowledge, not hypertext.

This is not exactly what I am saying. You are _not_ "given a URI for some 
resource in a system". You are given a simple identifier, a customer number, 
an order number, or a blog name. Not the complete URL. That "sitemap" tells 
the client where it can find the search forms for those numbers or names. By 
looking at the sitemap you can get a URL to the search form for customers. 
That search form tells you, that by doing a GET on a certain URL (the 
action) and passing the customer number as "&numer=...", you will get a 
resource describing the requested customer.

/J�rn

----- Original Message ----- 
From: "Eric J. Bowman" <eric@...>
To: "Jorn Wildt" <jw@...>
Cc: <rest-discuss@yahoogroups.com>
Sent: Monday, March 08, 2010 3:10 PM
Subject: Re: [rest-discuss] Re: Thoughts about URLs for a REST driven 
website


> "Jorn Wildt" wrote:
>>
>> Okay, so knowing the back-end URL format in the front-end is not
>> unRESTful. Fine, I'll accept that it is not strickly unRESTful
>> according to Roy's constraints.
>>
>
> Whenever I come across the notion of "Roy's REST" I can't help but
> wonder, what other REST is there?  If you have to qualify your REST
> implementation as based on something other than Roy's constraints, then
> you probably don't have REST.  ;-)
>
>>
>> It's just that it is brittle and, as
>> you say yourself, requires re-configuration of the front-end when the
>> back-end changes. It simply anoys me: no one have ever told me to
>> reconfigure my browser in order to lookup an ordernumber at Amazon,
>> just because they changed their internal implementation and URL
>> structure.
>>
>
> I said reconfigure the frontend, not reconfigure the client, though.
> The interaction between charger and wiski.org is hidden from the client,
> which is requesting ISO date-string translation from charger.  The
> wiski.org backend can change completely without affecting user-agent
> interaction with the frontend.  The frontend simply needs a new mapping
> to the backend, this has no effect on the client (unless you've embedded
> the backend URI in the request to the frontend).
>
>>
>> So neither solutions are perfect. What can we do instead?
>>
>
> I don't see any imperfection there.  I'll humor you, though, and point
> out that I could write the /date service proxy on charger to use an
> actual URI template from wiski.org.  I could then change the URI
> allocation scheme on wiski.org, update its URI template, and the /date
> service proxy on charger would automatically use the new URI allocation.
>
> You could do this, if you didn't mind adding complexity to support an
> optimization.  I'm just trying to get the point across, that if you do
> so you shouldn't point to it and say, "REST made me do it," because this
> notion is really neither here nor there as far as REST is concerned.
>
> As with any REST development, I can't stress enough that you should only
> apply those REST constraints that bring about a benefit to your project,
> while leaving room to add constraints in the future, as the system
> scales to a point where they make sense in terms of cost-benefit.  This
> applies also, to any additional constraints you may wish to add.
>
> So the question would be, in my case, what benefit would I achieve by
> basing the system on a dynamic URI template instead of hard-coding?
> The answer, even where REST constraints are involved, must make
> pragmatic sense to me -- the answer never comes down to REST dogma,
> only quantifiable benefits to the system.  I see none, in fact I see
> greater maintenance costs, so I'll let the hard-coding stand.
>
> Your concerns are valid for clients interacting with frontends, but
> they don't extend to the communication between layers in a system.  The
> wiski.org /date service and charger's /date proxy are both RESTful, even
> if the communication between charger and wiski.org isn't hypertext
> driven -- the API is, taken as a whole, as are its constituent parts.
>
> I'm perhaps overly-wordy in my explanation, it's just difficult for me
> to explain REST nuances to others, which come naturally to me for some
> reason... perhaps because I read Roy's thesis through twice each year,
> and refer to it regularly when engaged in REST development.
>
>>
>> > The wiski.org
>> > /date service will eventually have an Xforms interface to describe
>> > the API -- a URI template won't do, because the number of days in
>> > February is algorithmic.  But, that doesn't mean a client of the
>> > API is required to be an Xforms client, or otherwise consume that
>> > form.
>>
>> Yes. Publishing search forms in the back-end solves most of the
>> problems. Now my back-end has a way to instruct the front-end how to
>> fetch the ATOM resource referenced externally by the simple string
>> "peter".
>>
>
> Nuance, again.  Your back-end has a hypertext REST API which may be used
> to instruct generic user-agents how to interact with it, as well as to
> provide a self-documenting API which may be referenced by anyone
> developing a client specific to your API.  A client, i.e. the frontend,
> doesn't actually have to consume the hypertext -- all REST says is that
> the API must provide it.
>
> These are component implementation details, hidden behind the generic
> interface, and are thus out-of-scope to REST.  If you insist on applying
> some sort of constraint to component implementation, you can, but it
> isn't a REST constraint.  So, just as with any REST constraint, you'll
> need to evaluate its pros and cons -- except you can't do that by
> referring to REST since this constraint isn't in there.
>
>>
>> The same can be done programmatically in the front-end if just the
>> back-end has a machine-readable search form. This adds my required
>> flexibility at the cost of a bit more code in the front-end.
>>
>
> If this is a real requirement of your system, fine.  If you're doing
> this to "score REST points", don't -- there are none to be had.
>
>>
>> So what I am missing now is a standard format for publishing "these
>> are the ways you should access items using the REST API" - in a way
>> that can be parsed at runtime.
>>
>
> I don't understand.  Hypertext is the engine of application state.  I
> refer you again to my demo site.  All XHTML representations link to one
> XSLT transformation.  That XSLT transformation instructs the client, at
> runtime, how and when to dereference the /date service -- when it
> encounters a unique-to-page ISO 8601 date string, the XSLT code calls
> this template:
>
> <xsl:template name='date-service'>
> <xsl:param name='iso-date'/>
> <xsl:param name='date' 
> select="document(concat('../../date?iso=',$iso-date))//xht:p"/>
> <xsl:value-of select="concat($date/xht:abbr[1]/@title,', ')"/>
> <xsl:value-of select="concat($date/xht:abbr[2]/@title,' ')"/>
> <xsl:value-of select="concat($date/xht:abbr[3],' ')"/>
> <xsl:value-of select='$date/xht:span'/>
> </xsl:template>
>
> I don't know what a "standard format" would be, all I know is that
> there are many standard hypertext formats which may be employed to
> instruct clients how to use a REST API.  This is but one example, using
> standard media types -- charger sends some hypertext (XSLT in this
> case) which describes the use of a simple REST Web service, to replace
> one string with another of a specific format.
>
>>
>> 1) The official "here can you find the specs" kind of REST "sitemap".
>>
>
> This is exactly the opposite of what Roy means by, "A REST API should be
> entered with no prior knowledge beyond the initial URI."  If, given a
> URI for some resource in a system, I must consult some other "sitemap"
> resource before I can request another URI in the system, then the API
> is being driven by out-of-band knowledge, not hypertext.
>
> While my /date service currently lacks rel='up', that will eventually
> link all representations to the service document, i.e. an Xforms
> interface.  For now, though, regardless of entry point, any client that
> groks rel='next' and rel='prev' as Link headers can traverse the entire
> service output.  IOW, the entire service is accessible through each and
> every URI, this doesn't mean each and every URI needs a <form> of some
> sort.  HTH.
>
> -Eric 

Hi all,

I have a customer who raised a concern about REST "type safety". What he means may be best explained by a simple example.

Assume we have a resource that represents a folder, and by issueing a POST request, I can attach a file. What, however, if that post request wrongly goes to, let's say, another document resource instead of our folder, and the document resource also accepts POST (for some reason)?

In a RPC world, the document type would not understand an "addDocument()" call, and consequently return an exception. But what about REST? Of course, the POST's attributes most likely wouldn't be understood and something like 400 Bad Request returned. But what if they were understood?

So, are there means or patterns, to achieve (some sort) of type safety?

Thanks so much,
Juerg 


      

On Tue, Mar 9, 2010 at 9:48 AM, <jumeier@...> wrote:

>
>
> Hi all,
>
> I have a customer who raised a concern about REST "type safety". What he
> means may be best explained by a simple example.
>
> Assume we have a resource that represents a folder, and by issueing a POST
> request, I can attach a file. What, however, if that post request wrongly
> goes to, let's say, another document resource instead of our folder, and the
> document resource also accepts POST (for some reason)?
>
> In a RPC world, the document type would not understand an "addDocument()"
> call, and consequently return an exception. But what about REST? Of course,
> the POST's attributes most likely wouldn't be understood and something like
> 400 Bad Request returned. But what if they were understood?
>
> So, are there means or patterns, to achieve (some sort) of type safety?
>
> This is one of the reasons I prefer to use specific media types, instead of
generic things like "application/xml" or "application/json", for my
resources.  Then, if your "folder" resource accepts a media type that says
"here is a new document resource", but your document resource doesn't (it
accepts some other kind of POST request like "here is a comment to add to
the discussion about this document" with a different media type), then
you're fine ... a 4xx response would be appropriate (and, if you're using a
framework like JAX-RS for Java, the framework will take care of this
negotiation for you).  An an extra for-free bonus, you can set things up so
that the same resource can accept different POSTs (with different media
types) to trigger different state changes and server responses.  No need to
create 3 "artificial" resource URIs to support 3 different POSTs that
trigger state changes.

If you use a generic media type, then your "document resource" will need to
validate the details of the received input to make sure it obeys the rules
for what kind of behavior a POST should trigger on a document.  Of course,
you should be doing that anyway ... so it should be pretty obvious that the
incoming data doesn't have the right set of fields.  This kind of "form
validation" isn't really much different than what you should be doing in a
browser-based webapp, where the same scenario is possible.

> Thanks so much,
> Juerg
>
Craig

I would add to Craig's excellent reply that I've sometimes used a token
pattern to ensure tight control on updates to a server.

If I want to allow a client app to update the server but still maintain
tight control, I can require the client app to first request a ticket or
token that grants that client the permission to perform the update. This
token can be built any way the server wishes including using hash tags for
the enclosing resource (for POST) or some other value. You can easily make
the token time-limited and user- (or user-agent) specific, too. The way it
is constructed is of no consequence to the client, of course.

When the client performs the update (POST,PUT,DELETE) the value can be sent
as part of the state representation or, in cases where the message body does
not allow for this (e.g. binary uploads), the data can be included in as an
HTTP Header.

It's an extra step, but in cases where this information is critical and (as
Craig already pointed out) the media-type in use is insufficient for the
task, a validation token is useful.

mca
http://amundsen.com/blog/



On Tue, Mar 9, 2010 at 18:45, Craig McClanahan <craigmcc@...> wrote:

>
>
>
>
> On Tue, Mar 9, 2010 at 9:48 AM, <jumeier@...> wrote:
>
>>
>>
>> Hi all,
>>
>> I have a customer who raised a concern about REST "type safety". What he
>> means may be best explained by a simple example.
>>
>> Assume we have a resource that represents a folder, and by issueing a POST
>> request, I can attach a file. What, however, if that post request wrongly
>> goes to, let's say, another document resource instead of our folder, and the
>> document resource also accepts POST (for some reason)?
>>
>> In a RPC world, the document type would not understand an "addDocument()"
>> call, and consequently return an exception. But what about REST? Of course,
>> the POST's attributes most likely wouldn't be understood and something like
>> 400 Bad Request returned. But what if they were understood?
>>
>> So, are there means or patterns, to achieve (some sort) of type safety?
>>
>> This is one of the reasons I prefer to use specific media types, instead
> of generic things like "application/xml" or "application/json", for my
> resources.  Then, if your "folder" resource accepts a media type that says
> "here is a new document resource", but your document resource doesn't (it
> accepts some other kind of POST request like "here is a comment to add to
> the discussion about this document" with a different media type), then
> you're fine ... a 4xx response would be appropriate (and, if you're using a
> framework like JAX-RS for Java, the framework will take care of this
> negotiation for you).  An an extra for-free bonus, you can set things up so
> that the same resource can accept different POSTs (with different media
> types) to trigger different state changes and server responses.  No need to
> create 3 "artificial" resource URIs to support 3 different POSTs that
> trigger state changes.
>
> If you use a generic media type, then your "document resource" will need to
> validate the details of the received input to make sure it obeys the rules
> for what kind of behavior a POST should trigger on a document.  Of course,
> you should be doing that anyway ... so it should be pretty obvious that the
> incoming data doesn't have the right set of fields.  This kind of "form
> validation" isn't really much different than what you should be doing in a
> browser-based webapp, where the same scenario is possible.
>
>> Thanks so much,
>> Juerg
>>
> Craig
>
>
>
> 

On Mar 9, 2010, at 9:48 AM, <jumeier@...> <jumeier@...> wrote:

> I have a customer who raised a concern about REST "type safety". What he means may be best explained by a simple example.
> 
> Assume we have a resource that represents a folder, and by issueing a POST request, I can attach a file. What, however, if that post request wrongly goes to, let's say, another document resource instead of our folder, and the document resource also accepts POST (for some reason)?
> 
> In a RPC world, the document type would not understand an "addDocument()" call, and consequently return an exception. But what about REST? Of course, the POST's attributes most likely wouldn't be understood and something like 400 Bad Request returned. But what if they were understood?

Ah, yes, a similar thing happens all the time when
flaying frisbee in the park with my dog.  When I throw
the frisbee and the dog tries to catch it in his teeth,
everyone seems to be happy.  However, when the dog tries
to throw the frisbee and I try to catch it in my teeth,
it just doesn't seem to work well for either of us.

> So, are there means or patterns, to achieve (some sort) of type safety?

Yes.  A RESTful interface is one where the server provides the links
or forms that tells the client what operations to perform where.
If you are telling the client to do the wrong thing, then the
pattern would be to tell the client to do the right thing instead.
Generally speaking, it works out better that way.

....Roy

--- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
> On Feb 28, 2010, at 5:30 AM, Jan Vincent wrote:
> > In addition to this, is it feasible to access multiple REST web services, thereby maintaining more than one current 'state'?
> 
> Personally, I have not made up my mind on this. I guess that an application is limited to a single service unless the service itself point to another service itself.

So what about mashups? I.e., applications that combine data from two or more separate services on the fly, where none of the services were built in anticipation of the possible combination (and therefore don't link to the others)?

This seems like a common scenario in the Web, so I'd be interested to know how you explain the design of such systems in terms of REST.

Thanks,

Alistair

Alistair asks:

> So what about mashups? I.e., 
> applications that combine data from two or more separate services on the fly, 
> where none of the services were built in anticipation of the possible 
> combination (and therefore don't link to the others)?
>
> This seems like a  common scenario in the Web, so I'd be interested to know how you explain the 
> design of such systems in terms of REST.

While no expert, all "Mashup Studios" have to define data access to work.

For example, the Open Source Mashup system Apatar has Data Maps to define services.[1]  Online Mashups like Dapper have a wizard and the first question is "Enter a URL".[2]

Since most mashups are just doing GETs, this seems like the best/easiest case for RESTful services because the format of the URI is so predictable.

Mark W.

1. http://www.apatarforge.org
2. http://www.dapper.net/dapp-factory.jsp

OK. Let me add to that.

1. Let's no call it RPC, it is just plain method invocation, for the matter at hand it is the same thing. In this case, the idea of type safety works just the same. For objects, you have type checking when you send a message to the wrong object. You also have type checking when you send parameters. But there could be the case where two different object (different classes) have a method named the same, and receiving the same number of parameters, and the same parameter types too! In this case you face the exact problem. SO the problem goes down to a clumsy API definition and a lost programmer that makes the wrong calls.

2. Now, in REST you are supposed to create your client to discover state transitions. You start with one URL, and from there, each resource representation will tell you, through hypermedia, where can you go next and what info you need to provide, also which operations to execute to perform that transition. If that is in place, and you are writing the client to go post to a document URL manually (and thus, causing the error you mention) then it is your fault, not REST, since you are not following the rules.
On the other hand, if your resource representation provides the wrong URL, making your correctly programmed client to commit a mistake, then the one to blame is not REST, but the programmer that created the resource representation.

If you think about it, the same error you get using any other thing than REST.
Also, as with any other interaction technique, the one that receives data to be processed, should check the data is correct. If you send your social security number to a method expecting the time in milliseconds, you need to find a way in that method to validate the amount of milliseconds is a valid date. If it happens to be, then you are in trouble, being REST or not.

William Martinez.

--- In rest-discuss@yahoogroups.com, "Roy T. Fielding" <fielding@...> wrote:
>
> On Mar 9, 2010, at 9:48 AM, <jumeier@...> <jumeier@...> wrote:
> 
> > I have a customer who raised a concern about REST "type safety". What he means may be best explained by a simple example.
> > 
> > Assume we have a resource that represents a folder, and by issueing a POST request, I can attach a file. What, however, if that post request wrongly goes to, let's say, another document resource instead of our folder, and the document resource also accepts POST (for some reason)?
> > 
> > In a RPC world, the document type would not understand an "addDocument()" call, and consequently return an exception. But what about REST? Of course, the POST's attributes most likely wouldn't be understood and something like 400 Bad Request returned. But what if they were understood?
> 
> Ah, yes, a similar thing happens all the time when
> flaying frisbee in the park with my dog.  When I throw
> the frisbee and the dog tries to catch it in his teeth,
> everyone seems to be happy.  However, when the dog tries
> to throw the frisbee and I try to catch it in my teeth,
> it just doesn't seem to work well for either of us.
> 
> > So, are there means or patterns, to achieve (some sort) of type safety?
> 
> Yes.  A RESTful interface is one where the server provides the links
> or forms that tells the client what operations to perform where.
> If you are telling the client to do the wrong thing, then the
> pattern would be to tell the client to do the right thing instead.
> Generally speaking, it works out better that way.
> 
> ....Roy
>

J�rn Wildt wrote:
>
> > Whenever I come across the notion of "Roy's REST" I can't help but
> > wonder, what other REST is there?
> 
> :^)
> 

Maybe we could call say "Street REST" vs. "Roy's REST", one you pick up
on the street, the other by studying a doctoral dissertation...  As with
any language, street-speak is easier, but also less precise.

> 
> Yes, you won't have to reconfigure the browser client. But this may
> be one of the places where we disagree on what the "client" is. 
>

Oh, I'm sure we both know what a client is, in the general sense.  The
problem is that REST requires more precision.  "Client" in REST, can
mean a client component or a client connector.  We say user-agent when
we mean client component.  We _forget_ to say "origin server" to
distinguish between server components and server connectors.  We _ought_
to always qualify the terms "client" and "server" when discussing REST.

You're treating all clients as being of the same "class".  REST allows
that user-agents and gateways may both have client connectors, but only
the user-agent is a client component.  In my system, charger's /date
service implementation is a gateway (intermediary) component.  (Have I
been calling it a proxy?  Sorry folks, my bad.)

Different rules apply to the coding of user-agents and gateways.  From
the perspective of a protocol analyzer, however, requests to wiski.org
coming from the client connector on charger's gateway, or the client
connector of a user-agent manipulating a form, are indistinguishable.

A user-agent consuming the /date service, from either wiski.org or
charger, must be hypertext-driven.  The same constraint does not apply
to the gateway, where the rule is that implementation specifics are
hidden behind the generic interface (as implemented by the gateway's
client connector).

So the /date service on charger is an intermediary component known as a
gateway.  As currently configured, it has a client connector and a
server connector.  It can be expanded, through layering, such that
either the client connector or the server connector (or both), is behind
a cache connector.

My architectural philosophy will lead to a cache connector on the
server connector only, for both charger and wiski.org output.  This is
Greek to most folks.  When you fully understand REST, you'll be able to
tick off the pros and cons, by hear, of using a cache connector on the
server component vs. a reverse-proxy.

The only way to understand these things, is to become fluent in the
component-connector lingo of networked-software architecture -- this
precision is required in order to advance beyond StreetREST into
RoyREST.

>
> In my
> head I have a picture of a completely open back-end API. Open to the
> whole world that is. Anyone that can access the website can also
> access the REST API directly instead. I want everybody to be able to
> write different and/or better front-ends than I do. This means I
> don't have control over who consumes my back-end. In my scenario I
> have one REST API and a multitude of clients that uses it. One of
> these happens to be my own website.
> 

Exactly!  I couldn't have put it better myself.  I want the wiski.org 
/date translation service to be utilized far and wide.  While I haven't
provided a leap-year function, it's possible for anyone to code such a
function for their own app against the /date API.  If the cross-domain
language handling is a problem, like it is for my app, I've shown how
my front-end deals with the problem -- but that's just one possible
consumer of the service, and the pending Xforms service document is
just one other possible consumer of the service (when dereferenced by a
compatible user agent).

Without relying on 4xx response codes, a leap-year function can
dereference Feb 28th for a given year, and compare its rel='next' value
to the integer '29'.  Other services I haven't considered in my service
interface, or on my frontend, are possible -- because coders can infer
them from hypertext, not because their code is consuming a URI template
or a form.

A leap-year function is an ad-hoc REST client of the /date REST service.
This serendipitous re-use is made possible because a REST API is self-
documenting (otherwise coders couldn't infer anything from hypertext).
It would be a shame if serendipitous re-use were frowned on by REST,
for failing to be hypertext driven -- this would limit the usefulness
of any service to only the functionality its creator envisioned.

> 
> > The answer, even where REST constraints are involved, must make
> > pragmatic sense to me -- the answer never comes down to REST dogma,
> > only quantifiable benefits to the system.  I see none, in fact I see
> > greater maintenance costs, so I'll let the hard-coding stand.
> 
> Unfortunately, as a REST novice, I do not have experience enough with
> REST to really tell when it makes sense to use it or not. Well, maybe
> I do, but as newbies we often have to stick to the dogma since that
> is all we have. We don't have the experience and understanding that
> tells us that a specific part of REST can be left out or must be
> respected.
> 
> So it often comes down to dogma due to uncertainty of what will
> happen if we don't do everything stricly by the book.
> 

Stick to the thesis.  Chapter 5 is explicit about what the tradeoffs
are for each REST constraint; earlier chapters explain in more detail
what benefits result from which architectural styles.  Scale isn't
something everyone needs from the get-go.  You can make a decision about
whether to use cookies for auth, based on your projected need for scale
over time -- if you expect your system to grow huge, then you probably
won't want to rip out cookies later to facilitate growth.

Whereas if scale is never going to be a problem, then breaking a
constraint which facilitates scaling isn't a big deal.  You can read
through Roy's thesis and cherry-pick those benefits you need, and what
tradeoffs you're willing to make.  The appropriate constraints are then
added to the "null style," following the method laid out in the thesis.

The resulting architecture, having been devised through informed
decisions about benefits and drawbacks, would be firmly grounded in
networked-software theory.  As I've said before, REST is a tool, but to
make use of it requires the disciplined approach of modeling the
objectives of a system first, to have a blueprint for evaluating the
evolving implementation.

This process, informed by REST, may not always result in REST.  However,
if the result is an appropriate architecture for the system, any
criticism of it as unRESTful is purely dogmatic.  If, over time, the
system's evolution comes to require REST, the developers will already
be familiar with the discipline of REST development, and the notion of
adding constraints to achieve known benefits vs. known drawbacks.

-Eric

A response to the rest of your post is coming.

2010/3/10 Roy T. Fielding <fielding@...>

>
>
> Yes. A RESTful interface is one where the server provides the links
> or forms that tells the client what operations to perform where.
> If you are telling the client to do the wrong thing, then the
> pattern would be to tell the client to do the right thing instead.
>
>
All that is very well in a perfect world, but what if the client is of a
malicious nature, and it's nature lead him to overcome what the server
provides, by issuing a request that he may learned from introspection of
another application state?

On Mar 10, 2010, at 6:50 AM, Ant�nio Mota wrote:

> All that is very well in a perfect world, but what if the client is of a malicious nature, and it's nature lead him toovercome what the server provides, by issuing a request that he may learned from introspection of another application state?

It does not take out the responsibility of input validation and other security measures. The hypertext can very well include markers that the server can verify to deal with malicious clients.

(The recipes on one-time URIs in the RESTful Web Services Cookbook provide examples.) 

Subbu

Am 15.01.10 21:27, schrieb mike amundsen:

Hi,

> Recently, I've been thinking about how a coding framework or library
> can influence the way developers implement applications. What would a
> coding environment look like if it was meant to encourage results that
> followed a particular _architectural_ style (not programming style).
> 
> IOW, is there a way to craft a framework that constrains developers in
> ways that results in a REST-ful implementation of the application?

I'm currently toying around with implementing a restful service library
in clojure (See compojure-rest at github I you like.) What I have for
now is based on erlang's webmachine and I think it does not capture the
"essence" of REST.
> 
> I did some digging, but have yet to find any writing on this topic.
> 
> Here are some "off-the-top-of-my-head" items:
> 
> For example, a framework might exhibit these REST-like traits:
> - there is a clear separation of concerns between resource
> identifiers, resources, and representations
> - developers must define a resource as the public application interface
> - the Uniform Interface is enforced (e.g. those methods are the only
> public members exposed for a resource)
> - developers must always associate one or more representation formats
> with a resource and/or resource method before the implementation is
> valid
> - there is no way to define and use server-side session state objects
> 
> Some HTTP-specific traits might be:
> - support for content negotiation is "baked-in"
> - support for conditional requests is "baked-in" and automatic
> - RPC-like implementation patterns (e.g. gateway URIs) are somehow
> difficult to implement or are flagged as invalid

These items are a good start. I'd like to add the following:

- support for resource linking and qualification of links
- support for different abstract resource types
  - collections (including paging)
  - hierachical resources (refer to parent/childs/siblinks)
- mapping of URL to resource and vice versa. (The former is supported by
all web frameworks I know of, the latter by hardly any).

-billy.
-- 
404 signature not found.

>
> Ah, yes, a similar thing happens all the time when
> flaying frisbee in the park with my dog. When I throw
> the frisbee and the dog tries to catch it in his teeth,
> everyone seems to be happy. However, when the dog tries
> to throw the frisbee and I try to catch it in my teeth,
> it just doesn't seem to work well for either of us.
>

And your dog ends up complaining that you don't know how to do his job, is
it?


>
>
> > So, are there means or patterns, to achieve (some sort) of type safety?
>
> Yes. A RESTful interface is one where the server provides the links
> or forms that tells the client what operations to perform where.
> If you are telling the client to do the wrong thing, then the
> pattern would be to tell the client to do the right thing instead.
> Generally speaking, it works out better that way.
>
> ....Roy
>
>  
>

On Mar 10, 2010, at 6:50 AM, Ant�nio Mota wrote:
> 2010/3/10 Roy T. Fielding <fielding@...>
>> Yes. A RESTful interface is one where the server provides the links
>> or forms that tells the client what operations to perform where.
>> If you are telling the client to do the wrong thing, then the
>> pattern would be to tell the client to do the right thing instead.
>> 
> 
> All that is very well in a perfect world, but what if the client is of a malicious nature, and it's nature lead him to overcome what the server provides, by issuing a request that he may learned from introspection of another application state?

How is that relevant to type safety?  The only difference between
a strongly typed distributed system and a weakly typed distributed
system is that the former gives the attacker one more thing to lie
about.

The input has to be validated no matter how or where it has been defined.

....Roy

I am confused a bit about this. I was just thinking this today. If I provide a single URI point of entry, and an OPTION or GET request is sent, it returns some relevant links that can be called based on the state of the resource. Now, to get those links, I have to first access the point of entry URI. What happens if say a bot program (or even a client developer) decides to cache/save these URIs that return. Then at some point later, call those URIs directly instead of the point of entry URI first to get those URIs back. They could even navigate some links for a while, then save the various URIs deeper down. Later, call those directly.

My confusion of this is because the server side is stateless. It retains no state. So how can I validate a URI that a client/bot saved from some previous use, to make sure it's valid at the time of call? I have no state on the server side that says "this URI is being called BEFORE the URI that returns this URI was called.. it's a bad call". So I am unsure as to how to validate every single URI call to make sure it was called at a time when it should be called, and not just randomly out of order. I suppse we can use some sort of timestamp on every single URI that goes back, not sure entirely how that would work at this point, but I suppose the server would check this value when it came back in to the current server time stamp and make sure it's within so many minutes of when it was issued. But a smart client developer/bot could possibly figure that out, and update this value before making the request, and since the server keeps no state, if the modified
 timestamp is within the right time of the server, it would void that route of validating a URI.




> All that is very well in a perfect world, but what if the client is of a malicious nature, and it's nature lead him to overcome what the server provides, by issuing a request that he may learned from introspection of another application state?



How is that relevant to type safety?  The only difference between

a strongly typed distributed system and a weakly typed distributed

system is that the former gives the attacker one more thing to lie

about.



The input has to be validated no matter how or where it has been defined.




 



  






      

I've the same question... I don't believe there is any reason a client could not call more than one REST service to provide a robust UI with various pieces of different services. I can't imagine that REST dictates how a client is allowed to only access just the one service. Think of a store front site that makes use of paypal/google APIs along with perhaps a web cart REST service, and other mashups.


--- On Wed, 3/10/10, alistair.miles <alimanfoo@...> wrote:

From: alistair.miles <alimanfoo@...>
Subject: [rest-discuss] Re: Idea for a REST client
To: rest-discuss@yahoogroups.com
Date: Wednesday, March 10, 2010, 12:59 AM







 



  


    
      
      
      --- In rest-discuss@ yahoogroups. com, Jan Algermissen <algermissen1971@ ...> wrote:

> On Feb 28, 2010, at 5:30 AM, Jan Vincent wrote:

> > In addition to this, is it feasible to access multiple REST web services, thereby maintaining more than one current 'state'?

> 

> Personally, I have not made up my mind on this. I guess that an application is limited to a single service unless the service itself point to another service itself.



So what about mashups? I.e., applications that combine data from two or more separate services on the fly, where none of the services were built in anticipation of the possible combination (and therefore don't link to the others)?



This seems like a common scenario in the Web, so I'd be interested to know how you explain the design of such systems in terms of REST.



Thanks,



Alistair





    
     

    
    


 



  






      

On Fri, Mar 12, 2010 at 9:57 PM, Kevin Duffey <andjarnic@...> wrote:

> I am confused a bit about this. I was just thinking this today. If I
> provide a single URI point of entry, and an OPTION or GET request is
> sent, it returns some relevant links that can be called based on the
> state of the resource. Now, to get those links, I have to first
> access the point of entry URI. What happens if say a bot program (or
> even a client developer) decides to cache/save these URIs that
> return. Then at some point later, call those URIs directly instead
> of the point of entry URI first to get those URIs back. They could
> even navigate some links for a while, then save the various URIs
> deeper down. Later, call those directly.

A URI that is saved -- iow, bookmarked -- counts as an entry point
URI.  This sort of bookmarking is required to implement many kinds of
systems composed of multiple components that expose REST style
interfaces.

Of course, there is no guarantee that URIs saved by a client will
remain valid over time.  Clients that save URIs must accept that the
resources those URIs name may disappear as any point in the future.
Well behaved servers do not disable URIs capriciously (see Cool URIs),
but resources do have life-cycles that are governed by their domain.


> My confusion of this is because the server side is stateless. It
> retains no state. So how can I validate a URI that a client/bot
> saved from some previous use, to make sure it's valid at the time of
> call? I have no state on the server side that says "this URI is
> being called BEFORE the URI that returns this URI was called.. it's
> a bad call". So I am unsure as to how to validate every single URI
> call to make sure it was called at a time when it should be called,
> and not just randomly out of order. I suppse we can use some sort of
> timestamp on every single URI that goes back, not sure entirely how
> that would work at this point, but I suppose the server would check
> this value when it came back in to the current server time stamp and
> make sure it's within so many minutes of when it was issued. But a
> smart client developer/bot could possibly figure that out, and
> update this value before making the request, and since the server
> keeps no state, if the modified timestamp is within the right time
> of the server, it would void that route of validating a URI.

Why do you care if the resources are accessed "out of order"?

If there are domain reasons for a resource to be available for a
limited time, the application logic should destroy/deactivate the
resource once it is no longer valid.  In that case, this hypothetical
client with get a 410 or 404 when it attempts to make requests of the
now nonexistent resource.

If there is no domain reason for the resource to expire why is it a
problem for a client to save a URI and the access it later?

Peter
http://barelyenough.org

Hi Peter,
As for why I care.. I don't.. I thought it would not be HATEOAS if a URI could be accessed directly and not "discovered"? From all the posts, it seemed to me that if you accessed any URI directly, and not via an initial URI entry point that then gave you URIs you could use based on the resource state, I figured that was not the HATEOAS/REST way. I couldn't figure out how you could actually validate that a URI was called based on a URI you passed back previously, given the no state restraint in terms of resources on the server side.
I suppose tho, that a client should not save URIs for future direct access, as data may change, even resources could change, hence the ability to evolve the server side without breaking the client.

--- On Sat, 3/13/10, Peter Williams <pezra@...> wrote:

From: Peter Williams <pezra@...>
Subject: Re: [rest-discuss] HTTP request and "type safety"
To: "Kevin Duffey" <andjarnic@...>, "Rest List" <rest-discuss@yahoogroups.com>
Date: Saturday, March 13, 2010, 8:37 AM

On Fri, Mar 12, 2010 at 9:57 PM, Kevin Duffey <andjarnic@...> wrote:

> I am confused a bit about this. I was just thinking this today. If I
> provide a single URI point of entry, and an OPTION or GET request is
> sent, it returns some relevant links that can be called based on the
> state of the resource. Now, to get those links, I have to first
> access the point of entry URI. What happens if say a bot program (or
> even a client developer) decides to cache/save these URIs that
> return. Then at some point later, call those URIs directly instead
> of the point of entry URI first to get those URIs back. They could
> even navigate some links for a while, then save the various URIs
> deeper down. Later, call those directly.

A URI that is saved -- iow, bookmarked -- counts as an entry point
URI.� This sort of bookmarking is required to implement many kinds of
systems composed of multiple components that expose REST style
interfaces.

Of course, there is no guarantee that URIs saved by a client will
remain valid over time.� Clients that save URIs must accept that the
resources those URIs name may disappear as any point in the future.
Well behaved servers do not disable URIs capriciously (see Cool URIs),
but resources do have life-cycles that are governed by their domain.


> My confusion of this is because the server side is stateless. It
> retains no state. So how can I validate a URI that a client/bot
> saved from some previous use, to make sure it's valid at the time of
> call? I have no state on the server side that says "this URI is
> being called BEFORE the URI that returns this URI was called.. it's
> a bad call". So I am unsure as to how to validate every single URI
> call to make sure it was called at a time when it should be called,
> and not just randomly out of order. I suppse we can use some sort of
> timestamp on every single URI that goes back, not sure entirely how
> that would work at this point, but I suppose the server would check
> this value when it came back in to the current server time stamp and
> make sure it's within so many minutes of when it was issued. But a
> smart client developer/bot could possibly figure that out, and
> update this value before making the request, and since the server
> keeps no state, if the modified timestamp is within the right time
> of the server, it would void that route of validating a URI.

Why do you care if the resources are accessed "out of order"?

If there are domain reasons for a resource to be available for a
limited time, the application logic should destroy/deactivate the
resource once it is no longer valid.� In that case, this hypothetical
client with get a 410 or 404 when it attempts to make requests of the
now nonexistent resource.

If there is no domain reason for the resource to expire why is it a
problem for a client to save a URI and the access it later?

Peter
http://barelyenough.org



      

> I couldn't figure out how you could actually validate that a URI was called based on a URI you passed back previously, given the no state restraint in terms of resources on the server side.

Please see 

http://my.safaribooksonline.com/9780596809140/recipe-how-to-generate-one-time-uris

(sorry - requires a purchase to read)

Subbu

> 
> 
> --- On Sat, 3/13/10, Peter Williams <pezra@...> wrote:
> 
> From: Peter Williams <pezra@barelyenough.org>
> Subject: Re: [rest-discuss] HTTP request and "type safety"
> To: "Kevin Duffey" <andjarnic@...>, "Rest List" <rest-discuss@yahoogroups.com>
> Date: Saturday, March 13, 2010, 8:37 AM
> 
> On Fri, Mar 12, 2010 at 9:57 PM, Kevin Duffey <andjarnic@...> wrote:
> 
> > I am confused a bit about this. I was just thinking this today. If I
> > provide a single URI point of entry, and an OPTION or GET request is
> > sent, it returns some relevant links that can be called based on the
> > state of the resource. Now, to get those links, I have to first
> > access the point of entry URI. What happens if say a bot program (or
> > even a client developer) decides to cache/save these URIs that
> > return. Then at some point later, call those URIs directly instead
> > of the point of entry URI first to get those URIs back. They could
> > even navigate some links for a while, then save the various URIs
> > deeper down. Later, call those directly.
> 
> A URI that is saved -- iow, bookmarked -- counts as an entry point
> URI.  This sort of bookmarking is required to implement many kinds of
> systems composed of multiple components that expose REST style
> interfaces.
> 
> Of course, there is no guarantee that URIs saved by a client will
> remain valid over time.  Clients that save URIs must accept that the
> resources those URIs name may disappear as any point in the future.
> Well behaved servers do not disable URIs capriciously (see Cool URIs),
> but resources do have life-cycles that are governed by their domain.
> 
> 
> > My confusion of this is because the server side is stateless. It
> > retains no state. So how can I validate a URI that a client/bot
> > saved from some previous use, to make sure it's valid at the time of
> > call? I have no state on the server side that says "this URI is
> > being called BEFORE the URI that returns this URI was called.. it's
> > a bad call". So I am unsure as to how to validate every single URI
> > call to make sure it was called at a time when it should be called,
> > and not just randomly out of order. I suppse we can use some sort of
> > timestamp on every single URI that goes back, not sure entirely how
> > that would work at this point, but I suppose the server would check
> > this value when it came back in to the current server time stamp and
> > make sure it's within so many minutes of when it was issued. But a
> > smart client developer/bot could possibly figure that out, and
> > update this value before making the request, and since the server
> > keeps no state, if the modified timestamp is within the right time
> > of the server, it would void that route of validating a URI.
> 
> Why do you care if the resources are accessed "out of order"?
> 
> If there are domain reasons for a resource to be available for a
> limited time, the application logic should destroy/deactivate the
> resource once it is no longer valid.  In that case, this hypothetical
> client with get a 410 or 404 when it attempts to make requests of the
> now nonexistent resource.
> 
> If there is no domain reason for the resource to expire why is it a
> problem for a client to save a URI and the access it later?
> 
> Peter
> http://barelyenough.org
> 
> 
> 
> 

Kevin,

This issue of entry point URI vs. <<some other type of URI>> comes up from
time to time. Here is a post from a while ago from the middle of a previous
discussion of the issue. Roy schooled me one the subject. :-)

http://tech.groups.yahoo.com/group/rest-discuss/message/13616

Re: [rest-discuss] Newbie REST Question

On Fri, Oct 2, 2009 at 12:21 AM, Roy T. Fielding
<fielding@...<http://tech.groups.yahoo.com/group/rest-discuss/post?postID=SJClec4h4JuSITI9W3aFfYVckGf2FEUb9VZCMR0K7Fj8rfcWLW3zZbJ_-GyKvMgW5Bb4f_rP6x9S>>
wrote:
>> Where do you get the idea that not all URIs need be or should be cool?
(If I am understanding you correctly...)
>
> Umm, maybe the several hundred conversations I've had on
> the topic with TimBL in the room.  Cool URIs are permanent,
> so if you want to be cool then make permanence a design
> criteria.  That's all there is to it.

Agreed.

> Nobody is going to
> argue against too much URI permanence.  There is certainly
> nothing about that in conflict with REST, so if you perceive
> a conflict then I suggest you look at your reasoning and
> kill the paper tiger.

I'm glad to hear you confirm that there is no real conflict between URI
permanence and REST. I'm also glad to hear you confirm that there is no real
conflict between designs that depend on URI permanence and REST, eg
out-of-band URI templates. (Which is how I read your other
reply<http://tech.groups.yahoo.com/group/rest-discuss/message/13606>
.)

While others may use the word "conflict", for the record, I don't believe I
used the word "conflict" in this thread -- I used the word "tension". And I
quoted an email of
yours<http://tech.groups.yahoo.com/group/rest-discuss/message/12101>
from
back in February that seemed to indicate that you did not completely
disagree with the "tension" characterization:

*If there is a tension between the desire to bookmark and the fact that REST
encourages folks to break up an application into a state machine of reusable
resource states, then I would consider it to be more like sexual tension.
Just because you have it doesn't mean it is bad, and one way to improve
things is to make the more important resource links look sexier than the
less important ones.*


I suppose the fundamental tension here (and perhaps in sexual tension as
well -- who knows) is the tension between the desire for permanence and
stability vs. the desire for adaptability and change.

-- Nick


Nick Gall
Phone: +1.781.608.5871
Twitter: ironick
AOL IM: Nicholas Gall
Yahoo IM: nick_gall_1117
MSN IM: (same as email)
Google Talk: (same as email)
Email: nick.gall AT-SIGN gmail DOT com
Weblog: http://ironick.typepad.com/ironick/


On Sun, Mar 14, 2010 at 11:50 AM, Kevin Duffey <andjarnic@...> wrote:

>
>
> Hi Peter,
>
> As for why I care.. I don't.. I thought it would not be HATEOAS if a URI
> could be accessed directly and not "discovered"? From all the posts, it
> seemed to me that if you accessed any URI directly, and not via an initial
> URI entry point that then gave you URIs you could use based on the resource
> state, I figured that was not the HATEOAS/REST way. I couldn't figure out
> how you could actually validate that a URI was called based on a URI you
> passed back previously, given the no state restraint in terms of resources
> on the server side.
>
> I suppose tho, that a client should not save URIs for future direct access,
> as data may change, even resources could change, hence the ability to evolve
> the server side without breaking the client.
>
>
> --- On *Sat, 3/13/10, Peter Williams <pezra@...>* wrote:
>
>
> From: Peter Williams <pezra@...>
> Subject: Re: [rest-discuss] HTTP request and "type safety"
> To: "Kevin Duffey" <andjarnic@...>, "Rest List" <
> rest-discuss@yahoogroups.com>
> Date: Saturday, March 13, 2010, 8:37 AM
>
>
> On Fri, Mar 12, 2010 at 9:57 PM, Kevin Duffey <andjarnic@...<http://mc/compose?to=andjarnic@...>>
> wrote:
>
> > I am confused a bit about this. I was just thinking this today. If I
> > provide a single URI point of entry, and an OPTION or GET request is
> > sent, it returns some relevant links that can be called based on the
> > state of the resource. Now, to get those links, I have to first
> > access the point of entry URI. What happens if say a bot program (or
> > even a client developer) decides to cache/save these URIs that
> > return. Then at some point later, call those URIs directly instead
> > of the point of entry URI first to get those URIs back. They could
> > even navigate some links for a while, then save the various URIs
> > deeper down. Later, call those directly.
>
> A URI that is saved -- iow, bookmarked -- counts as an entry point
> URI.  This sort of bookmarking is required to implement many kinds of
> systems composed of multiple components that expose REST style
> interfaces.
>
> Of course, there is no guarantee that URIs saved by a client will
> remain valid over time.  Clients that save URIs must accept that the
> resources those URIs name may disappear as any point in the future.
> Well behaved servers do not disable URIs capriciously (see Cool URIs),
> but resources do have life-cycles that are governed by their domain.
>
>
> > My confusion of this is because the server side is stateless. It
> > retains no state. So how can I validate a URI that a client/bot
> > saved from some previous use, to make sure it's valid at the time of
> > call? I have no state on the server side that says "this URI is
> > being called BEFORE the URI that returns this URI was called.. it's
> > a bad call". So I am unsure as to how to validate every single URI
> > call to make sure it was called at a time when it should be called,
> > and not just randomly out of order. I suppse we can use some sort of
> > timestamp on every single URI that goes back, not sure entirely how
> > that would work at this point, but I suppose the server would check
> > this value when it came back in to the current server time stamp and
> > make sure it's within so many minutes of when it was issued. But a
> > smart client developer/bot could possibly figure that out, and
> > update this value before making the request, and since the server
> > keeps no state, if the modified timestamp is within the right time
> > of the server, it would void that route of validating a URI.
>
> Why do you care if the resources are accessed "out of order"?
>
> If there are domain reasons for a resource to be available for a
> limited time, the application logic should destroy/deactivate the
> resource once it is no longer valid.  In that case, this hypothetical
> client with get a 410 or 404 when it attempts to make requests of the
> now nonexistent resource.
>
> If there is no domain reason for the resource to expire why is it a
> problem for a client to save a URI and the access it later?
>
> Peter
> http://barelyenough.org
>
>
>
>
> 

Nick,



On Mar 14, 2010, at 10:01 PM, Nick Gall wrote:

> 
> I suppose the fundamental tension here (and perhaps in sexual tension as well -- who knows) is the tension between the desire for permanence and stability vs. the desire for adaptability and change.
> 

I think you wrongly see a tension there. Server evolvability is not negatively impacted by URI permanence. You do not degrade the freedom of the service owner to change the service by mandating cool URIs. All the server needs to do is to maintain the URIs (even if they return 301 or 410) and maintain the semantics of the resource they identify.

In fact, I think that those two things are the only elements of a Web application that a server *can* reasonably guarantee to keep stable and their stability allows the clients to maintain 'handles' (Bookmarks or 'open browser windows) to certain application states. This allows the client to efficiently jump back and forth between states to follow certain transitions. Freshness information and change notifications (303 See Other) allow the server to inform the client when it should refresh its views of these application states.

As a side note: it is a misconception about REST that a client can only use the current steady state to choose transitions. It can also go back in its own history to find certain transitions it is looking for. Likewise, it is perfectly fine to look at several steady states simultaneously to work towards some desired goal.


Jan

Volume 7 of This week in REST is up on the REST wiki -
http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Mar_8_2010
and the blog - http://wp.me/pMXr1-Q.

For contributing links this week visit
http://rest.blueoxen.net/cgi-bin/wiki.pl?RESTWeekly_Mar_15_2010

Note: the REST wiki is currently offline (anyone know who to contact to get it back up?), but the blog is alive and well

Cheers,
Ivan

Hi guys,

So who's in Vegas for mix this week and wants to grab a beer?

Seb

First, thanks to all for contributing so many ideas in this extensive thread!

--- On Wed, 3/10/10, Craig McClanahan <craigmcc@...> wrote:

From: Craig McClanahan <craigmcc@...>
Subject: Re: [rest-discuss] HTTP request and "type safety"
To: jumeier@...
Cc: rest-discuss@yahoogroups.com
Date: Wednesday, March 10, 2010, 12:45 AM



On Tue, Mar 9, 2010 at 9:48 AM,  <jumeier@...> wrote:
















�



  


    
      
      
      Hi all,



I have a customer who raised a concern about REST "type safety". What he means may be best explained by a simple example.



Assume we have a resource that represents a folder, and by issueing a POST request, I can attach a file. What, however, if that post request wrongly goes to, let's say, another document resource instead of our folder, and the document resource also accepts POST (for some reason)?




In a RPC world, the document type would not understand an "addDocument()" call, and consequently return an exception. But what about REST? Of course, the POST's attributes most likely wouldn't be understood and something like 400 Bad Request returned. But what if they were understood?




So, are there means or patterns, to achieve (some sort) of type safety?


This is one of the reasons I prefer to use specific media types, instead of generic things like "application/xml" or "application/json", for my resources.� Then, if your "folder" resource accepts a media type that says "here is a new document resource", but your document resource doesn't (it accepts some other kind of POST request like "here is a comment to add to the discussion about this document" with a different media type), then you're fine ... a 4xx response would be appropriate (and, if you're using a framework like JAX-RS for Java, the framework will take care of this negotiation for you).� An an extra for-free bonus, you can set things up so that the same resource can accept different POSTs (with different media types) to trigger different state changes and server responses.� No need to create 3 "artificial" resource URIs to support 3 different POSTs that trigger state changes.


>> Thanks for this interesting ideas with the media type. I made a similar observation - and now Roy will probably throw yet another frisbee - I looked at the new OASIS CMIS standard, more precisely at what they call "restful binding". This is based on HTTP and ATOM, with extensions. In the ATOM feeds/entries are number of attributes, that give certain hints on consistency, e.g. the doctype. But the problem I mentioned is solved as cmis:folder supports POST and no PUT, and document does exactly the contrary. Looks coherent to me.

>> As I am working mainly with Apache Sling, they introduced something called a "selector" as part of the URI. However, this controls renditions, thus applies for GETs only. But it's a good twist if you need radically different renditions from the same resource. E.g. /orders/123.list.html could provice a list with all line items, while /orders/123.tax.html may bring up information regarding tax calculations.

If you use a generic media type, then your "document resource" will need to validate the details of the received input to make sure it obeys the rules for what kind of behavior a POST should trigger on a document.� Of course, you should be doing that anyway ... so it should be pretty obvious that the incoming data doesn't have the right set of fields.� This kind of "form validation" isn't really much different than what you should be doing in a browser-based webapp, where the same scenario is possible.

>> Well, I definitely see that I can kiss goodbye the wonderful POST automisms from Sling...



Thanks so much,

Juerg 
Craig





      

--- On Wed, 3/10/10, Roy T. Fielding <fielding@...> wrote:

> From: Roy T. Fielding <fielding@...>
> Subject: Re: [rest-discuss] HTTP request and "type safety"
> To: jumeier@...
> Cc: rest-discuss@yahoogroups.com
> Date: Wednesday, March 10, 2010, 1:53 AM
> On Mar 9, 2010, at 9:48 AM, <jumeier@...>
> <jumeier@...>
> wrote:
> 
> > I have a customer who raised a concern about REST
> "type safety". What he means may be best explained by a
> simple example.
> > 
> > Assume we have a resource that represents a folder,
> and by issueing a POST request, I can attach a file. What,
> however, if that post request wrongly goes to, let's say,
> another document resource instead of our folder, and the
> document resource also accepts POST (for some reason)?
> > 
> > In a RPC world, the document type would not understand
> an "addDocument()" call, and consequently return an
> exception. But what about REST? Of course, the POST's
> attributes most likely wouldn't be understood and something
> like 400 Bad Request returned. But what if they were
> understood?
> 
> Ah, yes, a similar thing happens all the time when
> flaying frisbee in the park with my dog.� When I
> throw
> the frisbee and the dog tries to catch it in his teeth,
> everyone seems to be happy.� However, when the dog
> tries
> to throw the frisbee and I try to catch it in my teeth,
> it just doesn't seem to work well for either of us.

>> Roy, I hope this email finds your dog well. 
Sorry to double check on this image, but IMHO, images are a very good mean to transport abstract things like REST to customers. So, it'd prefer to have things clear.
So, you're suggesting that you are the server, the frisbee is the request, and the dog is the client? And *if* you are sending a bad message in the form of a poor shot or a very mal-formed frisbee, the dog won't be able to catch it? Thanks for clarification.

> 
> > So, are there means or patterns, to achieve (some
> sort) of type safety?
> 
> Yes.� A RESTful interface is one where the server
> provides the links
> or forms that tells the client what operations to perform
> where.
> If you are telling the client to do the wrong thing, then
> the
> pattern would be to tell the client to do the right thing
> instead.
> Generally speaking, it works out better that way.

>> Thanks for reminding me of the basic things in REST-life. Clearly the way to go. 
This just raises me one question. How would you flag to the client a link that is cool and MAY BE persisted, versus one that is of transient nature? 

Thanks,
-- Juerg


> 
> ....Roy
> 
> 


      

On Mar 16, 2010, at 3:05 PM, <jumeier@...> <jumeier@...> wrote:
> Sorry to double check on this image, but IMHO, images are a very good mean to transport abstract things like REST to customers. So, it'd prefer to have things clear.
> So, you're suggesting that you are the server, the frisbee is the request, and the dog is the client?

No, I was suggesting that the customer should not be
seeking RPC solutions (like type-safety checks) to apply
in a RESTful design where data is provided at the direct
instruction of the server.  The scenario doesn't make
any sense, unless of course the client isn't using REST
at all and merely thinks that HTTP == REST.

> This just raises me one question. How would you flag to the client a link that is cool and MAY BE persisted, versus one that is of transient nature? 

I would never use a transient link in the first place.
Even my redirect links are persistent.  Why do you need one?

....Roy

Hello all,

I am on a contract where the chaps are using ADO.NET Data Services (now WCF Data Services).

So I was wondering whether this qualifies as REST.  It has all the url structures and stuff but (as far as I can tell) that doesn't make it REST.

Just curious about what folks think about it.

Regards,
Eben

Hi Eben,


> I am on a contract where the chaps are using 
> target="_blank" href="http://ADO.NET">ADO.NET Data Services (now WCF Data 
> Services).

> So I was wondering whether this qualifies as REST.  It 
> has all the url structures and stuff but (as far as I can tell) that doesn't 
> make it REST.

O'Reilly has a book that covers using .Net 3.5 WCF to make RESTful web services.

http://oreilly.com/catalog/9780596519216

There's nothing RESTful about ADO.Net itself but MS created some URI parsing routines that are similar to Jersey's.

Cheers,

Mark W.

Bill - I'm replying and CCing the REST discussion group so they see
the message. I'm not involved in running the list but I hope someone
who follows the group can or knows someone else who can give you
access.

Can anyone please help Bill out or ping someone to let him post?

Thanks,
Ivan


On Wed, Mar 17, 2010 at 15:07, Bill Moseley <moseley@...> wrote:
> Hi Ivan,
> I noticed you posted about the rest Wiki on rest-discuss.
>
> By chance are you involved in running the list?  I signed up and posted a
> few messages but they have never shown up.  And I've had no luck getting a
> response from the moderators.
> I'm a member of the list:
> http://tech.groups.yahoo.com/group/rest-discuss/members?query=moseley&submit=Search&group=sub
> But if I try and post
> at: http://tech.groups.yahoo.com/group/rest-discuss/post there's a message
> that says:
>    Your message must be approved by the group owner before being sent to the
> group.
> And the messages I have sent none had shown up.
> Thanks,
>
> --
> Bill Moseley
> moseley@...
>

J�rn Wildt wrote:
>
> >> 1) The official "here can you find the specs" kind of REST
> >> "sitemap".
> >
> > This is exactly the opposite of what Roy means by, "A REST API
> > should be entered with no prior knowledge beyond the initial URI."
> 
> Then I am lost again :-(
> 

Let's see if we can't get you back on the path.

>
> > If, given a URI for some resource in a system, I must consult some
> > other "sitemap"
> > resource before I can request another URI in the system, then the
> > API is being driven by out-of-band knowledge, not hypertext.
> 
> This is not exactly what I am saying. You are _not_ "given a URI for
> some resource in a system". You are given a simple identifier, a
> customer number, an order number, or a blog name. Not the complete
> URL. That "sitemap" tells the client where it can find the search
> forms for those numbers or names. By looking at the sitemap you can
> get a URL to the search form for customers. That search form tells
> you, that by doing a GET on a certain URL (the action) and passing
> the customer number as "&numer=...", you will get a resource
> describing the requested customer.
> 

Given 2010-03-20 as a simple identifier, how is the client instructed
to build an URL with it?

Not REST:
Client has previously loaded some other document into memory (sitemap)
instructing it to make a GET for /date?iso=2010-03-20 when it encounters
an ISO date string.  Client "somehow knows" this out-of-band info.

REST:
Retrieved representation links to some other document (sitemap), which
may be cached locally, which contains a link for dereferencing.  Client
follows its nose -- i.e. checks another document for <a id='2010-03-20'
href='/date?iso=2010-03-20'>.

Also REST:
Retrieved representation contains some URL-construction code (perhaps a
form).  Client follows its nose -- the values '2010', '03' and '20' are
entered where appropriate.

Also REST:
Retrieved representation links to some document (not a sitemap) which
contains URL-construction code.  Client follows its nose -- in the case
of my demo, the retrieved representations link to an XSLT stylesheet
which (as I posted before) contains the code to convert ISO date-string
instances into URLs for dereferencing and transformation.

The key here, is for the client to follow hypertext included in the
representation which returns the "simple identifier", to learn how to
dereference an URL containing the "simple identifier".  While a
"sitemap" could be used, that really just adds another round-trip
between client and server.

What makes the Not REST example wrong, is that the client is expected to
know how to create the mapping using some knowledge outside (not linked)
the dereferenced representation which contains the "simple identifier".
For example, using a browser's client-side storage to cache a lookup
table, and using script to access name-value pairs from that client-side
storage for all subsequent requests.

While such a solution would work, the problem is that some prior URI
must be dereferenced to create this lookup table.  A dereferenced
representation containing a script which references client-side storage
would fail, unless that prior URI had been dereferenced.

When the condition is met, that the client can follow its nose (using
hypertext) to find everything needed to render a representation
dereferenced from some URI, then no prior knowledge is needed beyond
the URI being derefernced.

OTOH, if the URI being dereferenced cannot be rendered without the
client having prior knowledge of some other URI that the retrieved
representation doesn't link to, that prior knowledge is out-of-band.

To sum up, if your API requires me to first dereference some sort of
sitemap, before dereferencing any other URIs will work, then your API
must always be entered from the sitemap URI, instead of from any URI.

-Eric

Hi

In Martin Fowlers recent article on the Richardson maturity model for
REST (http://martinfowler.com/articles/richardsonMaturityModel.html),
he has an example of using link relations in a way that I haven't seen
much of before. Here's an example:

<link rel = "royalhope.nhs.uk/linkrels/appointment/updateContactInfo"
        uri = "patients/jsmith/contactInfo"/>

I find the link relationship to be very specific, reducing the value
of a uniform interface (a client would need to be familiar with this
specific rel type). In addition, the naming of the rel type in the
example looks suspiciously much like another place to put a method
name. I would be more comfortable with something like:

<link rel = "edit"
        type="vnd.contact.info"
        uri = "patients/jsmith/contactInfo"/>

But, there some very smart people who have reviewed the article, so
I'm sure there's a good reason for that example being that way it is.
It would be very interesting to hear your views on this.

/niklas

This use of "rel" is similar to the rel="stylesheet" use in common
browsers today. It's true that clients will need to understand the
meaning of these "rel" value in order to get the full benefit of their
use. This is part of the media-type definition which the client needs
to agree to when announcing support for the media type via the Accept
header in HTTP.

mca
http://amundsen.com/blog/




On Mon, Mar 22, 2010 at 11:35, Niklas Gustavsson <niklas@...> wrote:
> Hi
>
> In Martin Fowlers recent article on the Richardson maturity model for
> REST (http://martinfowler.com/articles/richardsonMaturityModel.html),
> he has an example of using link relations in a way that I haven't seen
> much of before. Here's an example:
>
> <link rel = "royalhope.nhs.uk/linkrels/appointment/updateContactInfo"
> � � � �uri = "patients/jsmith/contactInfo"/>
>
> I find the link relationship to be very specific, reducing the value
> of a uniform interface (a client would need to be familiar with this
> specific rel type). In addition, the naming of the rel type in the
> example looks suspiciously much like another place to put a method
> name. I would be more comfortable with something like:
>
> <link rel = "edit"
> � � � �type="vnd.contact.info"
> � � � �uri = "patients/jsmith/contactInfo"/>
>
> But, there some very smart people who have reviewed the article, so
> I'm sure there's a good reason for that example being that way it is.
> It would be very interesting to hear your views on this.
>
> /niklas
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

Niklas,

On Mar 22, 2010, at 4:35 PM, Niklas Gustavsson wrote:

> Hi
> 
> In Martin Fowlers recent article on the Richardson maturity model for
> REST (http://martinfowler.com/articles/richardsonMaturityModel.html),
> he has an example of using link relations in a way that I haven't seen
> much of before. Here's an example:
> 
> <link rel = "royalhope.nhs.uk/linkrels/appointment/updateContactInfo"
>        uri = "patients/jsmith/contactInfo"/>
> 
> I find the link relationship to be very specific, reducing the value
> of a uniform interface (a client would need to be familiar with this
> specific rel type). In addition, the naming of the rel type in the
> example looks suspiciously much like another place to put a method
> name.

It depends how this relation is defined (the actual name is meaningless). What the relation definition should do is to tell the client what the semantics of the target resource are. These semantics might include that a PUT to such a resource results in an update of something. This certainly makes not very much sense with PUT because PUT already means update.

Personally, I dislike such a design because it is (or at least looks like) yet another approach to give the usual OO-damaged developers what they think they need - instead of providing proper education.

So, +1 to your suspicions :-)


> I would be more comfortable with something like:
> 
> <link rel = "edit"
>        type="vnd.contact.info"
>        uri = "patients/jsmith/contactInfo"/>


What the above is missing is the semantics of "patients/jsmith/contactInfo". The correct way of doing it would be:

> <link rel = "royalhope.nhs.uk/linkrels/appointment/ContactInfo"
>        uri = "patients/jsmith/contactInfo"/>

to tell the cient where the contact info resource is. Given that, the client already knows that a PUT will do the update - if the client allows it.

The 'edit' link relation is used to tell clients where the single authorable resource is that should be used for a resource in question. For example, an Atom entry might appear in several collection s and thus have several member resources. The single one resource intended by the server for authoring can be linked to using the edit link.

The server could just as well acept a PUT to each member resource but redirect the PUT to the edit resource.


> 
> But, there some very smart people who have reviewed the article, so
> I'm sure there's a good reason for that example being that way it is.

I do not see one - I think it is bad design.

Jan


> It would be very interesting to hear your views on this.
> 
> /niklas
> 
> 
> ------------------------------------
> 
> Yahoo! Groups Links
> 
> 
> 

-----------------------------------
 Jan Algermissen, Consultant
 NORD Software Consulting

 Mail: algermissen@...
 Blog: http://www.nordsc.com/blog/
 Work: http://www.nordsc.com/
-----------------------------------